codegeist-ai · codegeist-ai · Aug 2, 2026 · Aug 2, 2026 · Aug 2, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,23 @@
+name: CI
+
+"on":
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Install Task
+        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        with:
+          version: "3.52.0"
+      - name: Run repository tests
+        run: task test
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,51 @@
+# Contributing To Codegeist Agent Kit
+
+This repository owns the generic OpenCode rules, commands, skills, helper
+scripts, plugins, and configuration shared by otherwise unrelated consuming
+repositories.
+
+## Shared Policies
+
+The account-wide Codegeist policies apply alongside this repository-specific
+guide:
+
+- [Contribution policy](https://github.com/codegeist-ai/.github/blob/main/CONTRIBUTING.md)
+- [Code of Conduct](https://github.com/codegeist-ai/.github/blob/main/CODE_OF_CONDUCT.md)
+- [Security policy](https://github.com/codegeist-ai/.github/blob/main/SECURITY.md)
+- [Support guide](https://github.com/codegeist-ai/.github/blob/main/SUPPORT.md)
+
+Do not report vulnerabilities or sensitive information in a public issue.
+
+## Choose The Owning Repository
+
+Changes belong here only when they are useful across repositories with
+unrelated products, architectures, and deployment models. Project-specific
+paths, workflows, deployment behavior, and product conventions belong in the
+consuming repository's `.oc_local/` commands, rules, or skills.
+
+Open an issue before starting when ownership or generic applicability is
+unclear.
+
+## Source Workflow
+
+1. Find or open a repository [Issue](https://github.com/codegeist-ai/codegeist-agent-kit/issues) and check the [Codegeist roadmap](https://github.com/users/codegeist-ai/projects/1).
+2. Use the linked specification under [`docs/tasks/`](docs/tasks/README.md) when one exists.
+3. Create a topic branch from the source `main` branch.
+4. Edit the source paths at the repository root. The generated `release` branch and consuming `.opencode/` checkouts are distribution outputs, not implementation targets.
+5. Run the normal repository check:
+
+```bash
+task test
+```
+
+6. Open a pull request that links the Issue and local task, summarizes the source and release impact, and reports verification.
+
+`task test` copies and validates the release bundle without creating commits,
+publishing a release, or updating submodules. Release publication through
+`task release-build` is maintainer-only and happens after source review.
+
+## License
+
+Codegeist-owned material and submitted contributions are accepted under the
+[Zero-Clause BSD License](LICENSE), SPDX identifier `0BSD`, without a separate
+CLA or DCO requirement. Preserve third-party licenses and notices.
diff --git a/INDEX.md b/INDEX.md
@@ -16,13 +16,19 @@ Agent-owned navigation map for the shared OpenCode workspace.
 - `rules/` - durable instructions loaded by `opencode.json`.
 - `skills/` - specialized workflows that can be loaded on demand.
 - `plugin/` - optional Graphify OpenCode integration.
+- `docs/tasks/` - source-repository task guide and local implementation specs
+  linked from public Issues.
+- `.github/workflows/ci.yml` - read-only contributor CI that runs `task test`.
 - `opencode.json` - runtime configuration that loads shared instructions,
   plugins, MCP servers, and permissions.
 - `playwright-mcp.json` - Playwright MCP browser launch configuration copied
   into the generated release bundle.
 - `README.md` - source-repository overview for maintainers.
+- `CONTRIBUTING.md` - generic-versus-local ownership and source contribution
+  workflow.
 - `README_release.md` - source file copied to `README.md` on the generated
   `release` branch.
+- `LICENSE` - canonical 0BSD license copied into the generated release bundle.
 - `Taskfile.yml` - release-copy, release-build, and smoke-test entrypoints.
 - `tests/release-copy.sh` - smoke test for the generated release bundle.
 
@@ -32,16 +38,20 @@ Agent-owned navigation map for the shared OpenCode workspace.
 
 ## Key Workflows
 
+- Start source contributions from `main`, use the linked Issue and local task,
+  and never implement changes in generated `release` or `.opencode/` checkouts.
 - Use `task test` after changing release runtime files or release-copy behavior.
-- Use `task release-build` only after reviewing `README_release.md` changelog
-  updates for consumer-visible changes.
+- Maintainers use `task release-build` only after source review and
+  `README_release.md` changelog updates for consumer-visible changes.
 - Use `/task spec "<title/context>"` and `/task impl <task-ref> [instructions]`
   for tracked task work.
 - Use `/update-index <directory>` to create or refresh directory-local indexes.
 
 ## Search Hints
 
 - `RELEASE_PATHS` - release bundle source paths in `Taskfile.yml`.
+- `docs/tasks/README.md` - Issue-to-task-to-PR linkage and status conventions.
+- `LICENSE` - 0BSD terms that must remain in source and release output.
 - `playwright-mcp.json` - browser config used by the shared Playwright MCP.
 - `/update-index` - command for creating or refreshing directory indexes.
 - `spec`, `impl` - task command actions for specification and implementation.
@@ -57,5 +67,6 @@ Agent-owned navigation map for the shared OpenCode workspace.
 ## Agent Notes
 
 - Keep this index compact because it is loaded into OpenCode instructions.
-- Keep this file outside the `.opencode` release submodule. Consuming
-  repositories own their root `INDEX.md` content.
+- Keep this file outside the `.opencode` release submodule while keeping
+  `LICENSE` in that bundle. Consuming repositories own their root `INDEX.md`
+  content.
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,7 @@
+BSD Zero Clause License
+
+Copyright (C) 2026 Codegeist contributors
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
diff --git a/README.md b/README.md
@@ -17,6 +17,13 @@ multiple repositories via a checked-out `.opencode/` directory.
 - `commands/` - shared slash-command definitions
 - `rules/` - shared durable workflow and editing rules
 - `skills/` - shared reusable skills
+- `docs/tasks/` - local implementation specifications linked from public Issues
+- `CONTRIBUTING.md` - repository-specific source contribution workflow
+- `LICENSE` - Zero-Clause BSD license for Codegeist-owned material
+- `README.md` - this source repository's contributor and maintainer guide; it is
+  not copied into the generated release
+- `README_release.md` - release consumer guide copied to `README.md` in the
+  generated `.opencode` bundle
 - `INDEX.md` - root agent navigation index for this source repository; it is not
   copied into the generated `.opencode` release submodule
 - `opencode.json` - OpenCode config for loading the shared rule set
@@ -36,8 +43,9 @@ multiple repositories via a checked-out `.opencode/` directory.
 
 Consuming repositories should add the generated `release` branch as their
 `.opencode` submodule. The release branch contains only the files needed at
-runtime: `.gitignore`, `README.md`, `opencode.json`, `playwright-mcp.json`,
-`ai-scripts/`, `commands/`, `rules/`, `skills/`, and `plugin/`.
+runtime: `.gitignore`, `LICENSE`, `README.md`, `opencode.json`,
+`playwright-mcp.json`, `ai-scripts/`, `commands/`, `rules/`, `skills/`, and
+`plugin/`.
 
 ```bash
 git submodule add -b release <repository-url> .opencode
@@ -50,12 +58,41 @@ To update an existing consuming repository to the latest release branch commit:
 git submodule update --remote .opencode
 ```
 
-Maintainers build and push the release branch from this repository with:
+After source review, maintainers build and push the release branch from this
+repository with:
 
 ```bash
 task release-build
 ```
 
+## Contributing
+
+Source work starts from `main` and a topic branch, never from the generated
+`release` branch or a consuming repository's `.opencode/` checkout. Read the
+[local contribution guide](CONTRIBUTING.md), find public work in
+[Issues](https://github.com/codegeist-ai/codegeist-agent-kit/issues) and the
+[Codegeist roadmap](https://github.com/users/codegeist-ai/projects/1), and use the
+[local task guide](docs/tasks/README.md) for accepted implementation
+specifications.
+
+The canonical normal check is non-publishing:
+
+```bash
+task test
+```
+
+Effective account-wide guidance is provided by the shared
+[contribution policy](https://github.com/codegeist-ai/.github/blob/main/CONTRIBUTING.md),
+[Code of Conduct](https://github.com/codegeist-ai/.github/blob/main/CODE_OF_CONDUCT.md),
+[security policy](https://github.com/codegeist-ai/.github/blob/main/SECURITY.md),
+and [support guide](https://github.com/codegeist-ai/.github/blob/main/SUPPORT.md).
+Codegeist-owned material is available under the [0BSD license](LICENSE).
+
+The visible [Codegeist account profile](https://github.com/codegeist-ai) is
+sourced from [`codegeist-ai/codegeist-ai`](https://github.com/codegeist-ai/codegeist-ai).
+The separate [`codegeist-ai/.github`](https://github.com/codegeist-ai/.github)
+repository remains the source of shared community defaults.
+
 ## Shared Vs Local
 
 Keep this repository repo-agnostic.
@@ -84,6 +121,9 @@ analysis flows should live in local overlays such as:
 
 ## Development Notes
 
+- Run `task test` after source changes. It validates a temporary release copy
+  without creating or publishing a release branch.
+- Release publication is maintainer-only after review.
 - `node_modules/` is ignored.
 - `package.json` and `package-lock.json` are local-only plugin files and are
   ignored because consuming workspaces do not require pinned plugin versions.
diff --git a/README_release.md b/README_release.md
@@ -26,17 +26,25 @@ configuration while leaving project-specific behavior in the consuming repo.
   and should only build or update graphs when the user explicitly asks for it.
 - `playwright-mcp.json` contains shared browser launch settings used by the
   `playwright` MCP server in `opencode.json`.
+- `LICENSE` carries the Zero-Clause BSD terms for Codegeist-owned material in
+  this distribution.
 
 The generated `release` branch is intentionally minimal. During release copy,
 this source file is renamed from `README_release.md` to `README.md`. The release
 branch should contain only runtime files needed by consuming repositories:
-`.gitignore`, `README.md`, `opencode.json`, `playwright-mcp.json`,
+`.gitignore`, `LICENSE`, `README.md`, `opencode.json`, `playwright-mcp.json`,
 `ai-scripts/`, `commands/`, `rules/`, `skills/`, and `plugin/`.
 
 ## Changelog
 
 ### Current Version
 
+- Changed `/task impl` to record successfully verified work as `solved` instead
+  of `implemented`, aligning generated task updates with the documented local
+  task lifecycle.
+- Added the canonical `0BSD` `LICENSE` to generated release bundles so the
+  distributed Codegeist-owned runtime content carries its license. No consumer
+  action is required beyond receiving a future submodule update.
 - Moved Playwright MCP snapshots, console logs, screenshots, and related output
   under the workspace-local ignored `.chrome/playwright-mcp/` directory instead
   of creating `.playwright-mcp/` at the workspace root.
@@ -191,6 +199,38 @@ Do not add product-specific deployment steps, architecture assumptions, branch
 names, or planning rules to the shared `.opencode` submodule unless they are
 intended to apply across all consuming repositories.
 
+## Contributing Upstream
+
+This checkout is generated distribution content. Propose generic shared
+OpenCode behavior in the
+[`codegeist-agent-kit` source repository](https://github.com/codegeist-ai/codegeist-agent-kit)
+from a topic branch based on source `main`; do not implement it on `release` or
+inside a consuming `.opencode/` checkout. Project-specific behavior belongs in
+the consuming repository's `.oc_local/` overlay.
+
+Use the source repository's
+[contribution guide](https://github.com/codegeist-ai/codegeist-agent-kit/blob/main/CONTRIBUTING.md),
+[Issues](https://github.com/codegeist-ai/codegeist-agent-kit/issues),
+[local task guide](https://github.com/codegeist-ai/codegeist-agent-kit/blob/main/docs/tasks/README.md),
+and the [Codegeist roadmap](https://github.com/users/codegeist-ai/projects/1).
+These links deliberately target source `main`; contributor docs and local task
+specifications are not files in this generated release bundle.
+The effective shared policies are the Codegeist
+[contribution policy](https://github.com/codegeist-ai/.github/blob/main/CONTRIBUTING.md),
+[Code of Conduct](https://github.com/codegeist-ai/.github/blob/main/CODE_OF_CONDUCT.md),
+[security policy](https://github.com/codegeist-ai/.github/blob/main/SECURITY.md),
+and [support guide](https://github.com/codegeist-ai/.github/blob/main/SUPPORT.md).
+The distributed files are licensed under [0BSD](LICENSE).
+
+The canonical source check is:
+
+```bash
+task test
+```
+
+It validates a temporary release copy without publishing. Release publication
+is maintainer-only after source review.
+
 ## Extending This Agent Kit
 
 A consuming repository can ask its coding agent to add reusable shared behavior

diff --git a/Taskfile.yml b/Taskfile.yml
@@ -20,7 +20,7 @@
 # - TEST_RELEASE_KEEP: set to `1` to keep the temp directory after `test-release`.
 #
 # Related files:
-# - README_release.md copied as README.md, opencode.json,
+# - README_release.md copied as README.md, LICENSE, opencode.json,
 #   playwright-mcp.json, ai-scripts/, commands/, rules/, skills/, plugin/
 # - INDEX.md is intentionally excluded from RELEASE_PATHS because it belongs to
 #   the consuming repository root, not the generated .opencode submodule.
@@ -32,7 +32,7 @@ vars:
   RELEASE_REMOTE: '{{default "origin" .RELEASE_REMOTE}}'
   RELEASE_SOURCE: '{{default "HEAD" .RELEASE_SOURCE}}'
   RELEASE_WORKTREE: '{{default ".release-build" .RELEASE_WORKTREE}}'
-  RELEASE_PATHS: README_release.md opencode.json playwright-mcp.json ai-scripts commands rules skills plugin
+  RELEASE_PATHS: README_release.md LICENSE opencode.json playwright-mcp.json ai-scripts commands rules skills plugin
   TEST_RELEASE_DIR: '{{default "" .TEST_RELEASE_DIR}}'
 
 tasks:

diff --git a/commands/task.md b/commands/task.md
@@ -98,7 +98,7 @@ implementation pass.
 git --no-pager diff --check
 ```
 
-9. Use status `implemented` when verification passes. Use `blocked` when a user
+9. Use status `solved` when verification passes. Use `blocked` when a user
    decision, failing dependency, or unresolved specification gap prevents safe
    implementation.
 

diff --git a/docs/tasks/README.md b/docs/tasks/README.md
@@ -0,0 +1,54 @@
+# Local Task Guide
+
+GitHub owns public work discovery and status. This directory keeps the focused
+implementation specifications accepted for this repository.
+
+## Linkage
+
+```text
+Codegeist roadmap -> repository Issue -> local task -> branch -> pull request -> merge
+```
+
+- The [Codegeist roadmap](https://github.com/users/codegeist-ai/projects/1) gives
+  the account-wide view.
+- A repository [Issue](https://github.com/codegeist-ai/codegeist-agent-kit/issues)
+  owns public discussion, priority, assignment, and status.
+- A local task owns the implementation goal, acceptance criteria, file scope,
+  non-goals, and verification.
+- A ready Issue links its local task path, and the task's `Public Tracking`
+  field links back with the full Issue URL.
+- The implementation branch and pull request link both the Issue and task. The
+  pull request reports verification and updates the task status when practical.
+- Merge closes the Issue and moves the public roadmap item to its completed
+  state. Historical task files remain implementation records, not ready work.
+
+Tasks start as `docs/tasks/TNNN_<slug>.md`, using the next available numeric ID.
+Only introduce nested task directories when a task genuinely needs child tasks.
+
+## Statuses
+
+- `open` - accepted local work that has not entered implementation.
+- `specified` - the task is clear enough to implement through `/task impl`.
+- `in progress` - implementation is active when the repository records this
+  intermediate state.
+- `blocked` - implementation cannot proceed until a named dependency or decision
+  is resolved.
+- `solved` - implementation, acceptance criteria, and local verification are
+  complete, but review or final handoff can still remain.
+- `finalized` - review and required handoff are complete and the task is kept as
+  a historical record.
+- `cancelled` - the task will not be implemented; the task records why.
+
+Local task status does not make work publicly ready. Public readiness is tracked
+separately: `Public Tracking` must contain an Issue URL, and the Issue or Roadmap
+item must be marked ready. A locally `open` or `specified` task with pending
+public tracking is not yet advertised contributor work.
+
+Backlog ideas without accepted scope stay in the repository Issue tracker or
+`docs/tasks/backlog.md`; they are not presented as ready implementation tasks.
+
+## Required Task Fields
+
+Each public candidate includes `Status`, `Public Tracking`, `Goal`, `Acceptance
+Criteria`, `Files`, `Non-Goals`, and `Verification`. Keep the specification
+small enough that a contributor can tell when it is complete.