diff --git a/.creed/config/development.md b/.creed/config/development.md index 35d905a..30b6761 100644 --- a/.creed/config/development.md +++ b/.creed/config/development.md @@ -32,12 +32,6 @@ are idempotent. - Tests should cover real behavior, not just compile-time existence. - Preserve deterministic output ordering for generated/synced files. -## Git / PR Rules - -- Commits should use Shiv's global git identity so GitHub verification works. -- Runner-generated commits may include `Co-authored-by: Archon ` for attribution. -- Auto-merge is permitted per the standing gate policy: CI green and gate confidence >= 0.80. - ## OpenSpec OpenSpec CLI is not installed on this machine. Edit files directly under `openspec/changes//` when creating or updating specs. diff --git a/.creed/manifest.yaml b/.creed/manifest.yaml index 264ebbf..72cc5b1 100644 --- a/.creed/manifest.yaml +++ b/.creed/manifest.yaml @@ -1,7 +1,13 @@ version: 1 source: - type: local + type: layered path: .creed + layers: + - name: org + type: git + remote: https://github.com/TechGodHQ/agent-context.git + path: .creed + ref: d678bf718664cd2f894279350f6a2010015c8af2 targets: - name: claude enabled: true diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3191f9a..3fa5e08 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -56,6 +56,22 @@ jobs: - name: Run golangci-lint run: golangci-lint run ./... + creed: + name: Creed context drift + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-go@v5 + with: + go-version-file: go.mod + + - name: Install released creed + run: go install github.com/techgodhq/creed@v0.4.1 + + - name: Emitted agent context must match the composed source + run: creed diff + security: name: Secret Scan runs-on: ubuntu-latest diff --git a/.gitignore b/.gitignore index e7f85f1..aed30b4 100644 --- a/.gitignore +++ b/.gitignore @@ -31,3 +31,6 @@ Thumbs.db .env .env.* !.env.example + +# Creed sync target metadata +.creed/.outputs/ diff --git a/AGENTS.md b/AGENTS.md index bc339a9..0cb5252 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,3 +1,226 @@ +# TechGodHQ Org Context + +TechGodHQ builds small, composable tools that are native to LLM use without +requiring an LLM at runtime. + +## Engineering Constitution + +- **One capability per repository.** Keep repository responsibilities narrow, + side effects explicit, and contracts composable. Prefer integrating focused + tools over absorbing adjacent capabilities. +- **LLM-native, LLM-optional.** Interfaces must be discoverable, deterministic, + non-interactive, and usable through structured inputs, outputs, and errors. + Core behavior must remain useful without an LLM. +- **Rust by default.** Build new production repositories in Rust. Document the + architectural reason for choosing another language. +- **One contract, projected surfaces.** Domain repositories define typed + capabilities. Hydra is the canonical mechanism for projecting those + contracts into CLI, HTTP, and MCP interfaces. Hydra-generated + adapters may live in other repositories; outside a documented temporary + legacy exception, independently designed or hand-written transport adapters + may not. +- **Integration evidence defines done.** Unit tests support a change but do not + prove it works. Exercise changed behavior through its real public boundary + and treat difficulty using it as a product defect. + +Before changing repository boundaries, dependencies, public contracts, or +transport surfaces, follow the Architecture Skill below. Before implementing +production behavior, follow the Implementation Skill below. Before reviewing +any pull request, follow the Org Review Skill below. + +## Public + MIT, Always + +All TechGodHQ repositories are public and MIT-licensed. Never create private +repositories or commit secrets. + +## Commit and Pull Request Rules + +- Shiv's global Git identity signs everything. +- Use conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`. +- Runner-generated work may carry + `Co-authored-by: Archon `. +- Omit tool-generated attribution footers. +- Land changes through pull requests rather than direct pushes to `main`. +- Auto-merge is permitted when CI is green and gate confidence is at least + 0.80. + +## Public Release Authority + +- Published tags and releases are immutable. Never move, delete, or rewrite a + published tag to repair release contents; publish a new, truthfully versioned + correction instead. +- Agents may prepare correction-release changes, update version constants and + release documentation, and run release verification without separate + approval. +- Publishing a new public tag or release requires Shiv's authorization unless + the linked ticket or its comments already explicitly authorize that exact + release. Existing explicit authorization is sufficient and must not be + requested twice. +- When authorization is absent, report an explicit `Blocked: release + authorization` state naming the proposed version. Do not silently re-plan or + leave the work parked without a labeled blocker. +- After authorization, verify the remote tag/release and a clean consumer + installation or equivalent public-boundary check before declaring the release + complete. + +--- + +# Architecture Skill + +Use when creating a TechGodHQ repository, adding a major capability, changing +repository boundaries or cross-repository dependencies, or introducing a CLI, +HTTP, MCP, or other public interface. + +## Process + +1. **State the responsibility.** Describe the repository's single coherent + capability in one sentence. A change belongs here only when that sentence + naturally owns it. +2. **Map composition.** Identify inputs, outputs, side effects, durable state, + and upstream and downstream contracts. Outputs should be usable as inputs + without scraping prose or reconstructing hidden state. +3. **Place the capability.** Reuse or extend the repository that already owns + it. Create a focused repository when the capability has an independent + lifecycle. Keep orchestration separate from domain behavior. +4. **Define the contract.** Prefer explicit typed contracts, structured errors, + deterministic behavior, and versionable schemas. Keep domain logic + independent of transport concerns. +5. **Project public surfaces through Hydra.** Domain repositories provide + Hydra-compatible contracts. Hydra generates CLI, HTTP, and MCP adapters + from those contracts. Generated adapters may be emitted into and + compiled by another repository, but that repository does not independently + design or hand-write the adapter. +6. **Close projection gaps at the source.** When Hydra cannot expose a required + contract, improve Hydra before adding a bespoke transport adapter. Record a + temporary legacy exception with its rationale and removal condition when an + immediate migration is genuinely impossible. +7. **Check dependency direction.** Reject circular dependencies, shared modules + that accumulate unrelated behavior, and integration that requires either + repository to understand the other's internals. + +## Completion Criteria + +The design is ready only when a reviewer can identify: + +- the repository's one responsibility; +- the owner of every capability and side effect; +- the stable contract between repositories; +- how each public surface is projected by Hydra; +- how another tool or agent can consume the result independently. + +--- + +# Implementation Skill + +Use when implementing or changing production behavior in a TechGodHQ +repository, including internal behavior whose correctness needs integration +evidence. + +## Implementation Rules + +- Use Rust when creating a new production repository. When another language is + required, document the architectural constraint and expected lifetime of + that repository-level exception. +- Keep the deterministic domain capability independent from any optional LLM + workflow around it. +- Make interfaces self-describing where practical. Prefer typed schemas, + structured inputs and outputs, stable error identifiers, and examples that + can be executed as written. +- Keep normal operation non-interactive. Require explicit inputs rather than + guessing intent, and make mutations and external side effects visible. +- Emit composable result data separately from diagnostics. Define partial + failure, retry, and idempotency behavior where side effects are involved. +- Generate CLI, HTTP, and MCP adapters through Hydra from the same domain + contract. Do not implement parallel transport semantics by hand. +- Keep generated artifacts deterministic and commit them when the repository's + workflow requires committed generated output. + +## Verification + +1. Run the repository's complete gate commands from `AGENTS.md`. +2. Add deterministic integration coverage at the nearest real public boundary + for every changed behavior where feasible. Unit tests remain useful for + isolated edge cases but are not sufficient evidence by themselves. +3. Exercise the change as a consumer would, through the public contract or a + Hydra-generated surface rather than an internal helper. +4. Where feasible, perform an agent acceptance pass: using only committed + repository guidance, have an unfamiliar agent discover the interface, + execute the changed behavior, and interpret the result. Record the exact + commands and observed result in the pull request. When it is infeasible, + record why and provide the strongest reproducible fallback evidence. +5. When a contract affects another repository, verify at least one real + producer-consumer path or a versioned contract fixture shared at that + boundary. + +An LLM is not part of deterministic CI merely because an agent performs the +acceptance pass. CI proves repeatable behavior; the acceptance pass proves that +the intended agent user can discover and operate it. + +## Completion Criteria + +The change is done only when the gates pass, feasible integration and agent +acceptance evidence cover the behavior, generated output is stable, and the +pull request contains enough evidence for a reviewer to reproduce the result. +Any omitted evidence includes an infeasibility rationale and the strongest +available fallback. + +--- + +# Org Review Skill + +Use when reviewing any TechGodHQ pull request. + +## Review Process + +1. Read the issue, specification, and repository responsibility before reading + the diff. Confirm the change satisfies the goal and belongs in this + repository. +2. Check architectural boundaries. Reject duplicated capabilities, unrelated + orchestration, circular dependencies, hidden cross-repository knowledge, + and side effects owned by the wrong component. +3. Check public surfaces. Domain repositories define typed contracts; Hydra + projects CLI, HTTP, and MCP adapters. Generated adapters may + reside in another repository, but independently designed or hand-written + transport adapters require a documented legacy exception. +4. Check LLM-native operation. An unfamiliar agent should be able to discover + the interface, supply structured input, run it non-interactively, interpret + structured output and errors, and compose the result without an LLM being a + runtime requirement. +5. Run the repository's complete gate commands from `AGENTS.md`. +6. Inspect verification evidence. Where feasible, require deterministic + integration coverage at the nearest real public boundary and the exact + commands and observed result from an agent acceptance pass. When either is + infeasible, require the reason and the strongest reproducible fallback. + Unit-only evidence is insufficient for externally observable behavior when + integration coverage is feasible. +7. Verify at least one producer-consumer path or versioned boundary fixture + when a cross-repository contract changes. +8. Check generated and synchronized output for determinism and drift when the + diff touches code generation, Hydra projection, or Creed-managed files. +9. Look for regressions in public contracts, schemas, structured errors, + idempotency, retry behavior, output composition, and explicit side effects. + +## Blocking Findings + +Block approval when the change: + +- weakens the repository's single responsibility for implementation + convenience; +- introduces a hand-written surface Hydra should project; +- requires an LLM for deterministic core behavior; +- omits feasible integration or agent-acceptance evidence, or omits the + infeasibility rationale and strongest reproducible fallback; +- cannot be operated from committed repository guidance; +- leaves generated output or cross-repository compatibility unverified. + +## Review Bias + +Prefer correctness, product behavior, composability, and reproducible evidence +over style nits. Raise style comments only when they prevent future bugs or +contract confusion. + +--- + # Creed Project Context Creed is a Go CLI that syncs AI agent context files across coding tools. The canonical source lives in `.creed/`; running `creed sync` emits tool-specific files such as `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/*`, and `GEMINI.md`. @@ -85,12 +308,6 @@ are idempotent. - Tests should cover real behavior, not just compile-time existence. - Preserve deterministic output ordering for generated/synced files. -## Git / PR Rules - -- Commits should use Shiv's global git identity so GitHub verification works. -- Runner-generated commits may include `Co-authored-by: Archon ` for attribution. -- Auto-merge is permitted per the standing gate policy: CI green and gate confidence >= 0.80. - ## OpenSpec OpenSpec CLI is not installed on this machine. Edit files directly under `openspec/changes//` when creating or updating specs. diff --git a/CLAUDE.md b/CLAUDE.md index bc339a9..0cb5252 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,3 +1,226 @@ +# TechGodHQ Org Context + +TechGodHQ builds small, composable tools that are native to LLM use without +requiring an LLM at runtime. + +## Engineering Constitution + +- **One capability per repository.** Keep repository responsibilities narrow, + side effects explicit, and contracts composable. Prefer integrating focused + tools over absorbing adjacent capabilities. +- **LLM-native, LLM-optional.** Interfaces must be discoverable, deterministic, + non-interactive, and usable through structured inputs, outputs, and errors. + Core behavior must remain useful without an LLM. +- **Rust by default.** Build new production repositories in Rust. Document the + architectural reason for choosing another language. +- **One contract, projected surfaces.** Domain repositories define typed + capabilities. Hydra is the canonical mechanism for projecting those + contracts into CLI, HTTP, and MCP interfaces. Hydra-generated + adapters may live in other repositories; outside a documented temporary + legacy exception, independently designed or hand-written transport adapters + may not. +- **Integration evidence defines done.** Unit tests support a change but do not + prove it works. Exercise changed behavior through its real public boundary + and treat difficulty using it as a product defect. + +Before changing repository boundaries, dependencies, public contracts, or +transport surfaces, follow the Architecture Skill below. Before implementing +production behavior, follow the Implementation Skill below. Before reviewing +any pull request, follow the Org Review Skill below. + +## Public + MIT, Always + +All TechGodHQ repositories are public and MIT-licensed. Never create private +repositories or commit secrets. + +## Commit and Pull Request Rules + +- Shiv's global Git identity signs everything. +- Use conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`. +- Runner-generated work may carry + `Co-authored-by: Archon `. +- Omit tool-generated attribution footers. +- Land changes through pull requests rather than direct pushes to `main`. +- Auto-merge is permitted when CI is green and gate confidence is at least + 0.80. + +## Public Release Authority + +- Published tags and releases are immutable. Never move, delete, or rewrite a + published tag to repair release contents; publish a new, truthfully versioned + correction instead. +- Agents may prepare correction-release changes, update version constants and + release documentation, and run release verification without separate + approval. +- Publishing a new public tag or release requires Shiv's authorization unless + the linked ticket or its comments already explicitly authorize that exact + release. Existing explicit authorization is sufficient and must not be + requested twice. +- When authorization is absent, report an explicit `Blocked: release + authorization` state naming the proposed version. Do not silently re-plan or + leave the work parked without a labeled blocker. +- After authorization, verify the remote tag/release and a clean consumer + installation or equivalent public-boundary check before declaring the release + complete. + +--- + +# Architecture Skill + +Use when creating a TechGodHQ repository, adding a major capability, changing +repository boundaries or cross-repository dependencies, or introducing a CLI, +HTTP, MCP, or other public interface. + +## Process + +1. **State the responsibility.** Describe the repository's single coherent + capability in one sentence. A change belongs here only when that sentence + naturally owns it. +2. **Map composition.** Identify inputs, outputs, side effects, durable state, + and upstream and downstream contracts. Outputs should be usable as inputs + without scraping prose or reconstructing hidden state. +3. **Place the capability.** Reuse or extend the repository that already owns + it. Create a focused repository when the capability has an independent + lifecycle. Keep orchestration separate from domain behavior. +4. **Define the contract.** Prefer explicit typed contracts, structured errors, + deterministic behavior, and versionable schemas. Keep domain logic + independent of transport concerns. +5. **Project public surfaces through Hydra.** Domain repositories provide + Hydra-compatible contracts. Hydra generates CLI, HTTP, and MCP adapters + from those contracts. Generated adapters may be emitted into and + compiled by another repository, but that repository does not independently + design or hand-write the adapter. +6. **Close projection gaps at the source.** When Hydra cannot expose a required + contract, improve Hydra before adding a bespoke transport adapter. Record a + temporary legacy exception with its rationale and removal condition when an + immediate migration is genuinely impossible. +7. **Check dependency direction.** Reject circular dependencies, shared modules + that accumulate unrelated behavior, and integration that requires either + repository to understand the other's internals. + +## Completion Criteria + +The design is ready only when a reviewer can identify: + +- the repository's one responsibility; +- the owner of every capability and side effect; +- the stable contract between repositories; +- how each public surface is projected by Hydra; +- how another tool or agent can consume the result independently. + +--- + +# Implementation Skill + +Use when implementing or changing production behavior in a TechGodHQ +repository, including internal behavior whose correctness needs integration +evidence. + +## Implementation Rules + +- Use Rust when creating a new production repository. When another language is + required, document the architectural constraint and expected lifetime of + that repository-level exception. +- Keep the deterministic domain capability independent from any optional LLM + workflow around it. +- Make interfaces self-describing where practical. Prefer typed schemas, + structured inputs and outputs, stable error identifiers, and examples that + can be executed as written. +- Keep normal operation non-interactive. Require explicit inputs rather than + guessing intent, and make mutations and external side effects visible. +- Emit composable result data separately from diagnostics. Define partial + failure, retry, and idempotency behavior where side effects are involved. +- Generate CLI, HTTP, and MCP adapters through Hydra from the same domain + contract. Do not implement parallel transport semantics by hand. +- Keep generated artifacts deterministic and commit them when the repository's + workflow requires committed generated output. + +## Verification + +1. Run the repository's complete gate commands from `AGENTS.md`. +2. Add deterministic integration coverage at the nearest real public boundary + for every changed behavior where feasible. Unit tests remain useful for + isolated edge cases but are not sufficient evidence by themselves. +3. Exercise the change as a consumer would, through the public contract or a + Hydra-generated surface rather than an internal helper. +4. Where feasible, perform an agent acceptance pass: using only committed + repository guidance, have an unfamiliar agent discover the interface, + execute the changed behavior, and interpret the result. Record the exact + commands and observed result in the pull request. When it is infeasible, + record why and provide the strongest reproducible fallback evidence. +5. When a contract affects another repository, verify at least one real + producer-consumer path or a versioned contract fixture shared at that + boundary. + +An LLM is not part of deterministic CI merely because an agent performs the +acceptance pass. CI proves repeatable behavior; the acceptance pass proves that +the intended agent user can discover and operate it. + +## Completion Criteria + +The change is done only when the gates pass, feasible integration and agent +acceptance evidence cover the behavior, generated output is stable, and the +pull request contains enough evidence for a reviewer to reproduce the result. +Any omitted evidence includes an infeasibility rationale and the strongest +available fallback. + +--- + +# Org Review Skill + +Use when reviewing any TechGodHQ pull request. + +## Review Process + +1. Read the issue, specification, and repository responsibility before reading + the diff. Confirm the change satisfies the goal and belongs in this + repository. +2. Check architectural boundaries. Reject duplicated capabilities, unrelated + orchestration, circular dependencies, hidden cross-repository knowledge, + and side effects owned by the wrong component. +3. Check public surfaces. Domain repositories define typed contracts; Hydra + projects CLI, HTTP, and MCP adapters. Generated adapters may + reside in another repository, but independently designed or hand-written + transport adapters require a documented legacy exception. +4. Check LLM-native operation. An unfamiliar agent should be able to discover + the interface, supply structured input, run it non-interactively, interpret + structured output and errors, and compose the result without an LLM being a + runtime requirement. +5. Run the repository's complete gate commands from `AGENTS.md`. +6. Inspect verification evidence. Where feasible, require deterministic + integration coverage at the nearest real public boundary and the exact + commands and observed result from an agent acceptance pass. When either is + infeasible, require the reason and the strongest reproducible fallback. + Unit-only evidence is insufficient for externally observable behavior when + integration coverage is feasible. +7. Verify at least one producer-consumer path or versioned boundary fixture + when a cross-repository contract changes. +8. Check generated and synchronized output for determinism and drift when the + diff touches code generation, Hydra projection, or Creed-managed files. +9. Look for regressions in public contracts, schemas, structured errors, + idempotency, retry behavior, output composition, and explicit side effects. + +## Blocking Findings + +Block approval when the change: + +- weakens the repository's single responsibility for implementation + convenience; +- introduces a hand-written surface Hydra should project; +- requires an LLM for deterministic core behavior; +- omits feasible integration or agent-acceptance evidence, or omits the + infeasibility rationale and strongest reproducible fallback; +- cannot be operated from committed repository guidance; +- leaves generated output or cross-repository compatibility unverified. + +## Review Bias + +Prefer correctness, product behavior, composability, and reproducible evidence +over style nits. Raise style comments only when they prevent future bugs or +contract confusion. + +--- + # Creed Project Context Creed is a Go CLI that syncs AI agent context files across coding tools. The canonical source lives in `.creed/`; running `creed sync` emits tool-specific files such as `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/*`, and `GEMINI.md`. @@ -85,12 +308,6 @@ are idempotent. - Tests should cover real behavior, not just compile-time existence. - Preserve deterministic output ordering for generated/synced files. -## Git / PR Rules - -- Commits should use Shiv's global git identity so GitHub verification works. -- Runner-generated commits may include `Co-authored-by: Archon ` for attribution. -- Auto-merge is permitted per the standing gate policy: CI green and gate confidence >= 0.80. - ## OpenSpec OpenSpec CLI is not installed on this machine. Edit files directly under `openspec/changes//` when creating or updating specs.