# AGENTS.md — parpour Agent Governance

## Scope

This file governs the entire **parpour** project (specification and planning workspace).

## Rules

1. **Spec-first discipline**: Update Venture specs (parpour root), CIV specs (sibling project), or root specs before any implementation in sibling projects.
2. **Determinism-first**: All specifications must define deterministic contracts. No "magic numbers" or hand-wave requirements.
3. **Fail loudly**: Call out unknowns explicitly in "Open Questions" sections (see NEXT_STEPS.md). Never leave ambiguities unresolved.
4. **Keep modules focused**: Each spec covers one domain (artifacts, treasury, policy, simulation loop, economy, etc.). Cross-spec dependencies are explicit.
5. **Run quality gates** (`task quality`) before marking work complete.
6. **Link implementation to specs**: Every task in NEXT_STEPS.md must reference spec section(s) it implements.

## Required References

- `NEXT_STEPS.md` — Implementation roadmap with P0/P1/P2 prioritization and open questions
- `SPECS_INDEX.md` — Master index of all 20 specification artifacts
- `docs/governance/GOVERNANCE_SUMMARY.md` — Baseline governance inherited from kush projects
- `docs/reference/WORK_STREAM.md` — Active work items, owners, and status tracking
- `docs/adr/` — Architecture decision records with rationale for key choices

## Agent Workflows

### Spec Review Workflow

When reviewing a spec for completeness:

1. Check all required sections are present (see `docs/governance/QUALITY_GATES.md`)
2. Verify all references to other specs are resolvable (no broken links)
3. Check for orphaned open questions (referenced in spec but not in NEXT_STEPS.md)
4. Validate consistency with dependent specs (transitive closure)
5. Run `task spec:validate` to confirm

### Work Claiming and Handoff

1. Review NEXT_STEPS.md to identify unclaimed P0 items
2. Update `docs/reference/WORK_STREAM.md`: add entry with `status: CLAIMED`, `owner: @your-name`, `started: YYYY-MM-DD`
3. Implement changes to affected specs
4. Run `task quality` to validate
5. Update WORK_STREAM.md: `status: COMPLETED`, `completed: YYYY-MM-DD`
6. Optionally write research notes to `docs/research/CONVERSATION_DUMP_YYYY-MM-DD.md`

### Cross-Project Coordination

Before updating `civ` or `venture` sibling projects:

1. Read relevant Venture specs in parpour root (`TECHNICAL_SPEC.md`, etc.) or CIV specs in sibling project
2. Check `docs/reference/WORK_STREAM.md` for related ongoing work
3. Implement changes in sibling project following their AGENTS.md rules
4. Update parpour WORK_STREAM.md with completion status
5. Note any spec gaps or questions discovered during implementation

## Anti-Patterns

| Bad | Good |
|-----|------|
| Update spec during implementation | Update spec first; implement second |
| Leave "TODO" or "???" in spec | Move to NEXT_STEPS.md "Open Questions" with owner + due date |
| Create new spec for edge case | Add section/subsection to existing spec; link from NEXT_STEPS.md |
| Copy-paste spec text between files | Define once; link with explicit "See {spec}, section X" references |
| Implement without reading full spec | Read spec first; add clarification questions to NEXT_STEPS.md if needed |
| Run quality before specs are updated | Update specs → run quality → implement |

## Quality Gate Targets

- **Spec coverage**: 100% of NEXT_STEPS.md P0/P1/P2 tasks traced to specs
- **Link validity**: 0 broken links between specs (automated check: `task spec:index`)
- **Open question resolution**: All Q1–Q8 in NEXT_STEPS.md have assigned owner + due date
- **Markdown lint**: 0 errors from `markdownlint-cli2`
- **Consistency**: No contradictions within a spec or between dependent specs (manual review)

## Escalation

If a spec is incomplete or contradictory:

1. **Blockers**: Record in NEXT_STEPS.md under "Open Questions" with owner + due date
2. **Design review**: Request sync with domain owner (listed in task description)
3. **Ambiguity**: Add clarifying example(s) to spec; if still unclear, escalate to NEXT_STEPS.md as Q{n}

## Success Criteria for Agent Task

A spec-driven agent task is complete when:

- [ ] All affected specs are updated
- [ ] `task quality` passes (no regressions)
- [ ] `task spec:validate` and `task spec:gaps` show 0 errors
- [ ] NEXT_STEPS.md open questions are resolved or assigned (owner + due date)
- [ ] WORK_STREAM.md is updated with completion status
- [ ] Research notes (optional) are written to docs/research/

## Governance Inheritance

parpour inherits core governance from:

- **Global kush project standards**: `~/.claude/CLAUDE.md` (security, no fallbacks, agent orchestration, library-first, dev philosophy)
- **Sibling thegent governance**: `~/.claude/docs/qa-governance-detail.md`, `~/.claude/docs/thegent-domain-patterns.md`
- **Project-specific overrides**: CLAUDE.md (this workspace, spec-first) and quality-gate.yml (markdown lint, spec coverage)

See `docs/governance/GOVERNANCE_SUMMARY.md` for full baseline.

---

## Venture Agent Personas & Delegation Guide

### Architect Agent

**Primary Role:** Spec authoring, design review, cross-system alignment.

**Best For:**
- Writing or updating core Venture specs (TECHNICAL_SPEC.md, TRACK_C_CONTROL_PLANE.md)
- Designing new artifact types (e.g., new SlideSpec variant)
- Reconciling CIV ↔ Venture integration points
- Creating architecture decision records (ADRs)
- Resolving architectural conflicts between domains

**Example Invocation:**
```bash
thegent research "Propose new artifact type for financial dashboards, aligned with ARTIFACT_COMPILER_SPEC.md" \
  --context "spec:ARTIFACT_COMPILER_SPEC.md" \
  --context "spec:SPECS_INDEX.md"
```

### Code Agent

**Primary Role:** Implementation, refactoring, testing.

**Best For:**
- Artifact compiler implementation (IR parsing, build pipeline, provenance)
- Treasury/ledger system (double-entry accounting, reconciliation)
- Control plane components (FSM, event bus, tool allowlists)
- Compliance machinery (policy evaluator, audit logging)
- Data models and schema implementations

**Example Invocation:**
```bash
thegent code "Implement artifact compiler build pipeline" \
  --context "spec:ARTIFACT_COMPILER_SPEC.md" \
  --context "spec:TRACK_A_ARTIFACT_DETERMINISM_SPEC.md" \
  --accept-criteria "deterministic builds, provenance metadata, schema validation"
```

### Review Agent

**Primary Role:** Code review, spec validation, quality assurance.

**Best For:**
- Peer review of spec changes or code
- Cross-track validation (CIV ↔ Venture alignment)
- Traceability audits (spec → implementation → tests)
- Security posture review (tool allowlists, event validation, credential handling)
- Compliance documentation review

**Example Invocation:**
```bash
thegent review "Audit TRACK_B implementation against TECHNICAL_SPEC.md and CIV-0100" \
  --context "spec:TRACK_B_TREASURY_COMPLIANCE_SPEC.md"
```

### Research Agent

**Primary Role:** Investigation, knowledge synthesis, cross-reference validation.

**Best For:**
- Exploring integration points (CIV ↔ Venture)
- Cross-spec validation (verifying consistency across all 12 Venture specs)
- Analyzing spec gaps and dependencies
- Summarizing complex requirements
- Creating traceability matrices

**Example Invocation:**
```bash
thegent research "Validate that all 5 CIV-Venture integration points (per SPECS_INDEX.md) are covered by our specs" \
  --context "spec:SPECS_INDEX.md" \
  --context "spec:TECHNICAL_SPEC.md,TRACK_B_TREASURY_COMPLIANCE_SPEC.md,TRACK_C_CONTROL_PLANE.md"
```

### General-Purpose Agent

**Primary Role:** Multi-step, multi-file tasks; orchestration.

**Best For:**
- Large refactoring across multiple specs
- Setting up governance infrastructure (Taskfile, linting, validation)
- Creating multi-file documentation structures
- Running validation pipelines
- Coordinating spec updates across domains

### Delegation Decision Tree

Use this flowchart to decide when to delegate vs. execute directly:

```
Task: [Your Request]
    │
    ├─ "Write/update a spec"? → Architect Agent
    ├─ "Implement code based on spec"? → Code Agent
    ├─ "Review or validate existing work"? → Review Agent
    ├─ "Research, validate specs, find gaps"? → Research Agent
    ├─ "Multi-file governance setup or large refactor"? → General-Purpose Agent
    └─ "Quick lookup, single file, <3 files"? → Execute Directly
```

### Task Taxonomies (Venture-Specific)

**Spec & Architecture Domain:**
- Design new artifact type → Architect
- Write ADR for major decision → Architect
- Reconcile CIV-Venture schemas → Architect + Research
- Validate spec completeness → Research
- Update spec for new requirement → Architect

**Implementation Domain:**
- Artifact compiler pipeline → Code
- Treasury ledger system → Code
- Control plane FSM & event bus → Code
- Tool allowlist enforcement → Code
- Audit logging & compliance → Code

**Governance & Infrastructure:**
- Taskfile setup → General-Purpose
- QA config and linting → General-Purpose
- Create docs/governance structure → General-Purpose
- Traceability matrix → Research or General-Purpose
- Cross-track validation → Research

**Code Review & Validation:**
- Security posture review → Review
- Spec-to-code traceability → Review
- Schema validation → Review
- Cross-reference audit → Review

### Common Venture Workflows

**Feature Addition (E.g., New Artifact Type):**
1. **Architect**: Design spec section for new artifact type
2. **Architect**: Create ADR
3. **Code**: Implement IR schema, build pipeline, tests
4. **Review**: Audit code against spec, security posture
5. **Research**: Validate SPECS_INDEX.md and cross-track dependencies
6. **You**: Run `task quality` and merge

**Cross-Track Bug Fix (CIV ↔ Venture):**
1. **Research**: Identify which integration point is failing
2. **Architect**: Propose fix and update specs
3. **Code**: Implement fix with test harness
4. **Review**: Verify determinism and replay guarantees
5. **You**: Run validation and merge

**Governance Infrastructure Setup:**
1. **General-Purpose**: Create Taskfile.yml, qa-config.json, docs/ structure
2. **You**: Review and adjust thresholds
3. **Review**: Validate all linting and validation rules
4. **You**: Run `task quality` to confirm

<!-- PHENOTYPE_GOVERNANCE_OVERLAY_V1 -->
## Phenotype Governance Overlay v1

- Enforce `TDD + BDD + SDD` for all feature and workflow changes.
- Enforce `Hexagonal + Clean + SOLID` boundaries by default.
- Favor explicit failures over silent degradation; required dependencies must fail clearly when unavailable.
- Keep local hot paths deterministic and low-latency; place distributed workflow logic behind durable orchestration boundaries.
- Require policy gating, auditability, and traceable correlation IDs for agent and workflow actions.
- Document architectural and protocol decisions before broad rollout changes.


## Bot Review Retrigger and Rate-Limit Governance

- Retrigger commands:
  - CodeRabbit: `@coderabbitai full review`
  - Gemini Code Assist: `@gemini-code-assist review` (fallback: `/gemini review`)
- Rate-limit contract:
  - Maximum one retrigger per bot per PR every 15 minutes.
  - Before triggering, check latest PR comments for existing trigger markers and bot quota/rate-limit responses.
  - If rate-limited, queue the retry for the later of 15 minutes or bot-provided retry time.
  - After two consecutive rate-limit responses for the same bot/PR, stop auto-retries and post queued status with next attempt time.
- Tracking marker required in PR comments for each trigger:
  - `bot-review-trigger: <bot> <iso8601-time> <reason>`


## Review Bot Governance

- Keep CodeRabbit PR blocking at the lowest level in `.coderabbit.yaml`: `pr_validation.block_on.severity: info`.
- Keep Gemini Code Assist severity at the lowest level in `.gemini/config.yaml`: `code_review.comment_severity_threshold: LOW`.
- Retrigger commands:
  - CodeRabbit: comment `@coderabbitai full review` on the PR.
  - Gemini Code Assist (when enabled in the repo): comment `@gemini-code-assist review` on the PR.
  - If comment-trigger is unavailable, retrigger both bots by pushing a no-op commit to the PR branch.
- Rate-limit discipline:
  - Use a FIFO queue for retriggers (oldest pending PR first).
  - Minimum spacing: one retrigger comment every 120 seconds per repo.
  - On rate-limit response, stop sending new triggers in that repo, wait 15 minutes, then resume queue processing.
  - Do not post duplicate trigger comments while a prior trigger is pending.

## Phenotype Org Cross-Project Reuse Protocol <!-- PHENOTYPE_SHARED_REUSE_PROTOCOL -->

- Treat this repository as part of the broader Phenotype organization project collection, not an isolated codebase.
- During research and implementation, actively identify code that is sharable, modularizable, splittable, or decomposable for reuse across repositories.
- When reusable logic is found, prefer extraction into existing shared modules/projects first; if none fit, propose creating a new shared module/project.
- Include a `Cross-Project Reuse Opportunities` section in plans with candidate code, target shared location, impacted repos, and migration order.
- For cross-repo moves or ownership-impacting extractions, ask the user for confirmation on destination and rollout, then bake that into the execution plan.
- Execute forward-only migrations: extract shared code, update all callers, and remove duplicated local implementations.
## Phenotype Git and Delivery Workflow Protocol <!-- PHENOTYPE_GIT_DELIVERY_PROTOCOL -->

- Use branch-based delivery with pull requests; do not rely on direct default-branch writes where rulesets apply.
- Prefer stacked PRs for multi-part changes so each PR is small, reviewable, and independently mergeable.
- Keep PRs linear and scoped: one concern per PR, explicit dependency order for stacks, and clear migration steps.
- Enforce CI and required checks strictly: do not merge until all required checks and policy gates are green.
- Resolve all review threads and substantive PR comments before merge; do not leave unresolved reviewer feedback.
- Follow repository coding standards and best practices (typing, tests, lint, docs, security) before requesting merge.
- Rebase or restack to keep branches current with target branch and to avoid stale/conflicting stacks.
- When a ruleset or merge policy blocks progress, surface the blocker explicitly and adapt the plan (for example: open PR path, restack, or split changes).
## Phenotype Long-Term Stability and Non-Destructive Change Protocol <!-- PHENOTYPE_LONGTERM_STABILITY_PROTOCOL -->

- Optimize for long-term platform value over short-term convenience; choose durable solutions even when implementation complexity is higher.
- Classify proposed changes as `quick_fix` or `stable_solution`; prefer `stable_solution` unless an incident response explicitly requires a temporary fix.
- Do not use deletions/reversions as the default strategy; prefer targeted edits, forward fixes, and incremental hardening.
- Prefer moving obsolete or superseded material into `.archive/` over destructive removal when retention is operationally useful.
- Prefer clean manual merges, explicit conflict resolution, and auditable history over forceful rewrites, force merges, or history-destructive workflows.
- Prefer completing unused stubs into production-quality implementations when they represent intended product direction; avoid leaving stubs ignored indefinitely.
- Do not merge any PR while any check is failing, including non-required checks, unless the user gives explicit exception approval.
- When proposing a quick fix, include a scheduled follow-up path to a stable solution in the same plan.