@davidorex/pi-jit-agents 0.26.0 → 0.28.0

package/templates/items/requirements.md

@@ -0,0 +1,20 @@
+{#-
+  Per-item macro for the `requirements` block (Plan 8 / per-item-macros wave 4).
+
+  Block schema: .project/schemas/requirements.schema.json. Each item is one
+  requirement inside data.requirements[]. Required: id (^REQ-\d{3,}$),
+  description, type, status, priority. Optional: acceptance_criteria,
+  source, traces_to (phase/task IDs), depends_on (other requirement IDs).
+
+  Cross-block reference recursion (traces_to, depends_on) is delegated to
+  shared/render-helpers.md — see that file for the depth contract, ambient
+  globals, and empty-array convention shared across all per-item macros.
+-#}
+{% from "shared/render-helpers.md" import render_id_list_inline %}
+
+{% macro render_requirement(req, depth=0) %}
+{% if req %}- **{{ req.id }}** [{{ req.priority }}] ({{ req.type }}, {{ req.status }}): {{ enforceBudget(req.description, "requirements", "requirements.items.description") }}{% if req.acceptance_criteria %}
+  Criteria: {% for ac in req.acceptance_criteria %}{{ enforceBudget(ac, "requirements", "requirements.items.acceptance_criteria.items") }}{% if not loop.last %}; {% endif %}{% endfor %}{% endif %}
+{% if req.source %}  Source: {{ req.source }}
+{% endif %}{{ render_id_list_inline("Traces to", req.traces_to, depth) }}{{ render_id_list_inline("Depends on", req.depends_on, depth) }}{% endif %}
+{% endmacro %}

package/templates/items/research.md

@@ -0,0 +1,57 @@
+{#-
+  Per-item macro for the `research` block.
+
+  Block schema: .project/schemas/research.schema.json (Plan 7 / per-item-macros wave 4).
+
+  Cross-block reference recursion (informs, informed_by, related_research,
+  produces_findings, supersedes, superseded_by) is delegated to
+  shared/render-helpers.md — see that file for the depth contract, ambient
+  globals, and empty-array convention.
+
+  Embedded substructures:
+    `grounding` is an object with dependencies/revisions/external_refs
+    string arrays — rendered inline as labelled sub-lists, never recursed.
+    `citations[]` carries label/path/lines/url/retrieved_at — labelled
+    pointers to source material, not block IDs; rendered inline.
+    `stale_conditions[]` and `scope[]` are simple string arrays rendered as
+    bullet sub-lists.
+
+  x-prompt-budget integration:
+    The schema annotates `findings_summary`, `question`, `method` with
+    `x-prompt-budget`. enforceBudget is wired for these per Plan 5.
+-#}
+{% from "shared/render-helpers.md" import render_id_list_block, render_id_single_block, render_optional_scalar %}
+
+{% macro render_research(r, depth=0) %}
+ID: {{ r.id }}
+Title: {{ r.title }}
+Status: {{ r.status }}
+Layer: {{ r.layer }}
+Type: {{ r.type }}
+Created by: {{ r.created_by }}
+Created at: {{ r.created_at }}
+{{ render_optional_scalar("Modified by", r.modified_by) }}{{ render_optional_scalar("Modified at", r.modified_at) }}{{ render_optional_scalar("Conducted by", r.conducted_by) }}{{ render_optional_scalar("Conducted at", r.conducted_at) }}{{ render_optional_scalar("Grounded at", r.grounded_at) }}
+Question:
+{{ enforceBudget(r.question, "research", "research.items.question") }}
+
+Method:
+{{ enforceBudget(r.method, "research", "research.items.method") }}
+
+{% if r.scope is defined %}Scope:
+{% if r.scope | length > 0 %}{% for s in r.scope %}  - {{ s }}
+{% endfor %}{% else %}  (none)
+{% endif %}{% endif %}Findings summary:
+{{ enforceBudget(r.findings_summary, "research", "research.items.findings_summary") }}
+
+{% if r.findings_document %}Findings document: {{ r.findings_document }}
+{% endif %}{% if r.grounding is defined %}Grounding:
+{% if r.grounding.dependencies is defined %}  Dependencies: {% if r.grounding.dependencies | length > 0 %}{% for d in r.grounding.dependencies %}{{ d }}{% if not loop.last %}, {% endif %}{% endfor %}{% else %}(none){% endif %}
+{% endif %}{% if r.grounding.revisions is defined %}  Revisions: {% if r.grounding.revisions | length > 0 %}{% for rv in r.grounding.revisions %}{{ rv }}{% if not loop.last %}, {% endif %}{% endfor %}{% else %}(none){% endif %}
+{% endif %}{% if r.grounding.external_refs is defined %}  External refs: {% if r.grounding.external_refs | length > 0 %}{% for er in r.grounding.external_refs %}{{ er }}{% if not loop.last %}, {% endif %}{% endfor %}{% else %}(none){% endif %}
+{% endif %}{% endif %}{% if r.stale_conditions is defined %}Stale conditions:
+{% if r.stale_conditions | length > 0 %}{% for sc in r.stale_conditions %}  - {{ sc }}
+{% endfor %}{% else %}  (none)
+{% endif %}{% endif %}{% if r.citations is defined %}Citations:
+{% if r.citations | length > 0 %}{% for c in r.citations %}  - {{ c.label }}{% if c.path %} — path: {{ c.path }}{% if c.lines %}:{{ c.lines }}{% endif %}{% endif %}{% if c.url %} — url: {{ c.url }}{% endif %}{% if c.retrieved_at %} — retrieved_at: {{ c.retrieved_at }}{% endif %}
+{% endfor %}{% else %}  (none)
+{% endif %}{% endif %}{{ render_id_list_block("Informs", r.informs, depth) }}{{ render_id_list_block("Informed by", r.informed_by, depth) }}{{ render_id_list_block("Related research", r.related_research, depth) }}{{ render_id_list_block("Produces findings", r.produces_findings, depth) }}{{ render_id_list_block("Supersedes", r.supersedes, depth) }}{{ render_id_single_block("Superseded by", r.superseded_by, depth) }}{% endmacro %}

package/templates/items/spec-reviews.md

@@ -0,0 +1,51 @@
+{#-
+  Per-item macro for the `spec-reviews` block.
+
+  Block schema: .project/schemas/spec-reviews.schema.json (Plan 7 / per-item-macros wave 4).
+
+  Findings:
+    Each review carries an embedded findings registry (definitions/finding
+    in the schema). Findings are rendered inline as a sub-list under the
+    review body — they are not block items in their own right and have no
+    per-item macro of their own. Each finding's `produces_decision` (when
+    present and depth > 0) recurses into the decisions block via
+    resolve/render_recursive — that pattern stays inline because it has a
+    deeper indent (4 spaces) than the helper convention assumes and is
+    embedded in a finding-iteration loop rather than a top-level field.
+    `related_findings` on a finding refer to sibling findings within the
+    same review by their string ids; they are emitted as bare IDs (no
+    recursion — finding IDs are scoped to the review and not in the global
+    ID index).
+
+  Optional review-level scalars (target_revision, reviewer, completed_at,
+  clean) and the method body delegate to shared/render-helpers.md
+  render_optional_scalar where the shape matches.
+-#}
+{% from "shared/render-helpers.md" import render_optional_scalar %}
+
+{% macro render_spec_review(rev, depth=0) %}
+ID: {{ rev.id }}
+Target: {{ rev.target }}
+Status: {{ rev.status }}
+Created by: {{ rev.created_by }}
+Created at: {{ rev.created_at }}
+{{ render_optional_scalar("Target revision", rev.target_revision) }}{{ render_optional_scalar("Reviewer", rev.reviewer) }}{{ render_optional_scalar("Completed at", rev.completed_at) }}{% if rev.clean is defined %}Clean: {{ rev.clean }}
+{% endif %}{% if rev.method %}Method:
+{{ enforceBudget(rev.method, "spec-reviews", "reviews.items.method") }}
+
+{% endif %}{% if rev.scope is defined %}Scope:
+{% if rev.scope | length > 0 %}{% for s in rev.scope %}  - {{ s }}
+{% endfor %}{% else %}  (none)
+{% endif %}{% endif %}Findings:
+{% if rev.findings and rev.findings | length > 0 %}{% for f in rev.findings %}  - {{ f.id }} [{{ f.severity }}/{{ f.category }}/{{ f.state }}] reporter={{ f.reporter }} at={{ f.created_at }}
+    Description: {{ enforceBudget(f.description, "spec-reviews", "reviews.items.findings.items.description") }}
+{% if f.evidence %}    Evidence: {{ f.evidence }}
+{% endif %}{% if f.location %}    Location: {{ f.location }}
+{% endif %}{% if f.resolution %}    Resolution: {{ f.resolution }}
+{% endif %}{% if f.resolved_by %}    Resolved by: {{ f.resolved_by }}
+{% endif %}{% if f.resolved_at %}    Resolved at: {{ f.resolved_at }}
+{% endif %}{% if f.produces_decision %}    Produces decision: {% if depth > 0 %}{% set loc = resolve(f.produces_decision) %}{% if loc %}
+{{ render_recursive(loc, depth - 1) }}{% else %}{{ f.produces_decision }}{% endif %}{% else %}{{ f.produces_decision }}{% endif %}
+{% endif %}{% if f.related_findings is defined %}    Related findings: {% if f.related_findings | length > 0 %}{% for rf in f.related_findings %}{{ rf }}{% if not loop.last %}, {% endif %}{% endfor %}{% else %}(none){% endif %}
+{% endif %}{% endfor %}{% else %}  (none)
+{% endif %}{% endmacro %}

package/templates/items/tasks.md

@@ -0,0 +1,29 @@
+{#-
+  Per-item macro for the `tasks` block (Plan 8 / per-item-macros wave 4).
+
+  Block schema: .project/schemas/tasks.schema.json. Each item is one task
+  inside data.tasks[]. Required: id (^TASK-\d{3,}$), description, status.
+  Optional: phase (string|integer), files, acceptance_criteria, depends_on
+  (other task IDs), assigned_agent, verification (verification ID), notes.
+
+  When status === "completed", schema additionally requires verification
+  (the if/then conditional in the schema).
+
+  Cross-block reference recursion (depends_on, verification) is delegated to
+  shared/render-helpers.md — see that file for the depth contract, ambient
+  globals, and empty-array convention. verification is rendered as a single
+  inline reference (one ID) rather than a list.
+
+  Files field:
+    files[] is a list of code paths, not project-block IDs. Rendered inline
+    as a comma-separated list; never recursed.
+-#}
+{% from "shared/render-helpers.md" import render_id_list_inline, render_id_single_inline %}
+
+{% macro render_task(t, depth=0) %}
+{% if t %}- **{{ t.id }}** [{{ t.status }}]: {{ enforceBudget(t.description, "tasks", "tasks.items.description") }}{% if t.phase %} (phase {{ t.phase }}){% endif %}{% if t.files %} — files: {{ t.files | join(", ") }}{% endif %}
+{% if t.acceptance_criteria %}  Criteria: {% for ac in t.acceptance_criteria %}{{ enforceBudget(ac, "tasks", "tasks.items.acceptance_criteria.items") }}{% if not loop.last %}; {% endif %}{% endfor %}
+{% endif %}{% if t.assigned_agent %}  Assigned agent: {{ t.assigned_agent }}
+{% endif %}{% if t.notes %}  Notes: {{ enforceBudget(t.notes, "tasks", "tasks.items.notes") }}
+{% endif %}{{ render_id_list_inline("Depends on", t.depends_on, depth) }}{{ render_id_single_inline("Verification", t.verification, depth) }}{% endif %}
+{% endmacro %}

package/templates/phase-author/task.md

@@ -0,0 +1,82 @@
+## Intent
+
+{{ intent }}
+
+## Existing Phases
+
+{% for phase in phases %}
+- Phase {{ phase.number }}: {{ phase.name }} ({{ phase.status }})
+{% endfor %}
+
+{% if architecture and architecture.modules %}
+## Current Architecture
+
+{% for module in architecture.modules %}
+- **{{ module.name }}** ({{ module.file }}, {{ module.lines }} lines): {{ module.responsibility }}
+{% endfor %}
+
+{% if architecture.compilation_pipeline %}
+### Compilation Pipeline
+{% for stage in architecture.compilation_pipeline %}
+{{ loop.index }}. **{{ stage.stage }}**: {{ stage.description }}
+{% endfor %}
+{% endif %}
+{% endif %}
+
+{% if conventions and conventions.rules %}
+## Conventions
+
+{% for rule in conventions.rules %}
+- {{ rule.id }}: {{ rule.description }} ({{ rule.enforcement }})
+{% endfor %}
+{% endif %}
+
+{% if gaps and gaps.gaps %}
+## Current Gaps
+
+{% for gap in gaps.gaps %}
+{% if gap.status == "open" %}
+- [{{ gap.priority }}] {{ gap.id }}: {{ gap.description }}
+{% endif %}
+{% endfor %}
+{% endif %}
+
+{% if inventory %}
+## Current Inventory
+
+{% if inventory.step_types %}- Step types: {{ inventory.step_types | length }}
+{% endif %}{% if inventory.agent_specs %}- Agent specs: {{ inventory.agent_specs | length }}
+{% endif %}{% if inventory.schemas %}- Schemas: {{ inventory.schemas | length }}
+{% endif %}{% if inventory.test_count is defined %}- Tests: {{ inventory.test_count }}
+{% endif %}{% endif %}
+
+## Instructions
+
+Convert the intent above into a structured phase spec. Read the codebase to understand what exists and what the intent requires.
+
+1. **Determine the phase number** — next after the highest existing phase number
+2. **Write a clear intent statement** — what this phase accomplishes and why
+3. **Define success criteria** — each with a verify_method:
+   - `command`: can be verified by running a shell command (test suite, grep, validate)
+   - `inspect`: requires reading files and assessing content
+   - `human`: requires human judgment
+4. **Decompose into specs** — each spec is a focused unit of work:
+   - Sequential numbering continuing from the last spec in the previous phase
+   - Clear intent per spec
+   - Concrete acceptance criteria (strings, each independently checkable)
+   - Specs should be ordered by dependency — earlier specs don't depend on later ones
+5. **Identify dependencies** — which phase numbers this phase depends on
+6. **List artifacts produced** — file paths this phase will create or modify
+
+### Sizing guidance
+
+- Each spec should be completable by one agent in one context window
+- If a spec needs more than ~5 files changed, split it
+- If a spec has more than ~5 acceptance criteria, it might be doing too much
+- Group related changes (e.g., schema + instance + validation test = one spec)
+
+### Cross-reference gaps
+
+Check if any existing open gaps are addressed by this phase. If so, note that in the spec intent — the gap can be marked resolved when the spec completes.
+
+Produce a JSON object conforming to the phase schema.

package/templates/plan-creator/task.md

@@ -0,0 +1,143 @@
+## Project Identity
+
+**Name:** {{ project.name }}
+**Description:** {{ project.description }}
+**Core Value:** {{ project.core_value }}
+**Status:** {{ project.status }}
+{% if project.stack %}
+
+### Stack
+{% for item in project.stack %}
+- {{ item }}
+{% endfor %}
+{% endif %}
+
+## Requirements Summary
+
+{% for req in requirements.requirements %}
+{% if req.priority == "must" %}
+- **{{ req.id }}** [must/{{ req.type }}]: {{ req.description }}
+{% endif %}
+{% endfor %}
+{% for req in requirements.requirements %}
+{% if req.priority == "should" %}
+- **{{ req.id }}** [should/{{ req.type }}]: {{ req.description }}
+{% endif %}
+{% endfor %}
+{% for req in requirements.requirements %}
+{% if req.priority == "could" %}
+- **{{ req.id }}** [could/{{ req.type }}]: {{ req.description }}
+{% endif %}
+{% endfor %}
+
+## Architecture
+
+**Overview:** {{ architecture.overview }}
+
+### Modules
+{% for module in architecture.modules %}
+- **{{ module.name }}** (`{{ module.file }}`): {{ module.responsibility }}{% if module.dependencies %} [depends: {{ module.dependencies | join(", ") }}]{% endif %}
+{% endfor %}
+
+### Patterns
+{% for pattern in architecture.patterns %}
+- **{{ pattern.name }}**: {{ pattern.description }} (used in: {{ pattern.used_in | join(", ") }})
+{% endfor %}
+
+### Boundaries
+{% for boundary in architecture.boundaries %}
+- {{ boundary }}
+{% endfor %}
+
+{% if existing_files %}
+## Existing Project Files
+
+The project directory already contains these files:
+{% for file in existing_files %}
+- {{ file }}
+{% endfor %}
+
+Account for existing structure — do not plan to recreate files that already exist unless they need modification.
+{% endif %}
+
+## Instructions
+
+Create implementation phases and tasks that build this project incrementally. The plan should take the project from its current state ({{ project.status }}) to a working system that satisfies all "must" requirements and addresses "should" requirements.
+
+### Phase guidelines
+
+1. **Phase 1** — Foundation: project structure, core module scaffolding, configuration, initial tests
+2. **Phase 2+** — Layer functionality in priority order: "must" requirements first, then "should"
+3. **Final phase** — Integration, documentation, and verification
+4. Each phase should represent a meaningful milestone — the project is more capable after each phase
+5. A phase with more than 8-10 tasks is likely too large — split it
+
+### For each phase, provide:
+
+- **number** — sequential starting at 1
+- **name** — short descriptive name
+- **intent** — what this phase accomplishes and why it comes at this point
+- **goal** — what is true after this phase that was not true before
+- **status** — `"planned"`
+- **success_criteria** — array of `{ criterion, verify_method }` (verify_method: "command", "inspect", or "test")
+- **dependencies** — array of phase numbers this depends on (empty for phase 1)
+- **inputs** — what this phase needs from prior phases or external sources
+- **outputs** — what this phase produces for later phases or users
+
+### For each task, provide:
+
+- **id** — unique, formatted as T-001, T-002, etc.
+- **description** — clear statement of what to do
+- **status** — `"planned"`
+- **phase** — phase number this belongs to
+- **files** — array of file paths this task creates or modifies
+- **acceptance_criteria** — array of specific, verifiable statements
+- **depends_on** — array of task IDs this depends on (empty if none)
+- **notes** — optional: any implementation guidance or caveats
+
+### Task sizing
+
+- Each task should be completable by one agent in one context window
+- A task touching more than 3-5 files likely needs splitting
+- A task with more than 5 acceptance criteria may be doing too much
+- Group related changes: schema + implementation + test = one task when files are few
+
+### Traceability
+
+- Every "must" requirement should be addressed by at least one task
+- Every task's files should map to at least one architecture module
+- Note requirement IDs in task descriptions or notes where the mapping is clear
+
+### Output format
+
+Produce a single JSON object with two arrays:
+
+```json
+{
+  "phases": [
+    {
+      "number": 1,
+      "name": "string",
+      "intent": "string",
+      "goal": "string",
+      "status": "planned",
+      "success_criteria": [{ "criterion": "string", "verify_method": "command" }],
+      "dependencies": [],
+      "inputs": ["string"],
+      "outputs": ["string"]
+    }
+  ],
+  "tasks": [
+    {
+      "id": "T-001",
+      "description": "string",
+      "status": "planned",
+      "phase": 1,
+      "files": ["src/file.ts"],
+      "acceptance_criteria": ["string"],
+      "depends_on": [],
+      "notes": "optional string"
+    }
+  ]
+}
+```

package/templates/plan-decomposer/task.md

@@ -0,0 +1,46 @@
+## Phase: {{ phase.name }}
+
+### Intent
+{{ phase.intent }}
+
+### Success Criteria
+{% for criterion in phase.success_criteria %}
+- {{ criterion.criterion }} (verify: {{ criterion.verify_method }})
+{% endfor %}
+
+### Specs
+{% if phase.specs %}
+{% for spec in phase.specs %}
+- **{{ spec.id }}**: {{ spec.name }}
+{% endfor %}
+{% endif %}
+
+### Current Architecture
+{% for module in architecture.modules %}
+- **{{ module.name }}** ({{ module.file }}): {{ module.responsibility }}
+{% endfor %}
+
+### Conventions
+{% for rule in conventions.rules %}
+- {{ rule.id }}: {{ rule.description }} ({{ rule.enforcement }})
+{% endfor %}
+
+## Instructions
+
+Decompose this phase into implementation plans. Each plan should be a focused unit of work that one agent can complete in a single context window.
+
+Before creating plans:
+1. Read source files referenced in the architecture to understand existing patterns
+2. Identify logical boundaries — which specs or features are independent
+3. Determine which plans can run in parallel (independent file sets)
+
+For each plan, produce:
+- **name**: short identifier for the plan
+- **intent**: what this plan accomplishes and why
+- **tasks**: concrete list of things to do (create files, add tests, wire up)
+- **files_to_change**: paths that will be created or modified
+- **acceptance_criteria**: how to know the plan is done
+- **context_needed**: files or modules the implementing agent should read first
+- **parallel_group**: group name — plans in the same group can run concurrently (independent file sets get the same group; dependent plans get different groups)
+
+Output a JSON object with a `plans` array conforming to the plan-breakdown schema.

package/templates/project-definer/task.md

@@ -0,0 +1,67 @@
+## Vision Statement
+
+{{ vision }}
+
+{% if context %}
+## Additional Context
+
+{{ context }}
+{% endif %}
+
+## Instructions
+
+Produce a structured project identity from the vision statement above. Extract, infer, or derive each field — do not leave gaps where the vision provides signal.
+
+### Fields to produce
+
+1. **name** — short, lowercase-hyphenated project identifier
+2. **description** — 1-3 sentences capturing what the project does and why it matters
+3. **core_value** — one sentence a stakeholder outside the project could understand
+4. **target_users** — array of user roles or personas who benefit
+5. **constraints** — array of `{ type, description }` objects reflecting real limitations from the vision
+   - type examples: "technical", "organizational", "timeline", "budget", "regulatory", "compatibility"
+6. **scope_boundaries** — `{ in: [...], out: [...] }` capturing what is and is not in scope
+   - `out` is especially important: document what a reader might assume is in scope but is not
+7. **goals** — array of `{ id, description, success_criteria: [...] }` objects
+   - IDs: G-001, G-002, etc.
+   - success_criteria: measurable or verifiable statements (not aspirational)
+8. **status** — set to `"inception"`
+
+{% if stack %}
+### Stack
+
+The following technology stack has been specified:
+
+{% for item in stack %}
+- {{ item }}
+{% endfor %}
+
+Include these in the output `stack` array.
+{% endif %}
+
+{% if repository %}
+### Repository
+
+Repository: {{ repository }}
+
+Include this in the output `repository` field.
+{% endif %}
+
+### Output format
+
+Produce a single JSON object. Every required field must be present. The object should conform to the project block schema:
+
+```json
+{
+  "name": "string (required)",
+  "description": "string (required)",
+  "core_value": "string (required)",
+  "target_users": ["string"],
+  "constraints": [{ "type": "string", "description": "string" }],
+  "scope_boundaries": { "in": ["string"], "out": ["string"] },
+  "goals": [{ "id": "G-001", "description": "string", "success_criteria": ["string"] }],
+  "status": "inception",
+  "repository": "string (if provided)",
+  "stack": ["string (if provided)"]
+}
+```

package/templates/project-inferrer/task.md

@@ -0,0 +1,56 @@
+Infer the project identity for the project at `{{ path }}`.
+
+## Codebase Analysis
+
+{% if exploration.files is defined %}
+### Files ({{ exploration.files | length }} total)
+{% for file in exploration.files | batch(20) | first %}
+- `{{ file.path }}` ({{ file.language | default("unknown") }})
+{% endfor %}
+{% if exploration.files | length > 20 %}
+... and {{ exploration.files | length - 20 }} more files
+{% endif %}
+{% endif %}
+
+{% if exploration.entryPoints is defined %}
+### Entry Points
+{% for ep in exploration.entryPoints %}
+- `{{ ep }}`
+{% endfor %}
+{% endif %}
+
+## Instructions
+
+Read project metadata and documentation to determine the project's identity. Start with:
+- README.md (or equivalent)
+- Package manifest (package.json, Cargo.toml, pyproject.toml, go.mod, etc.)
+- CLAUDE.md or similar project instructions if present
+- CI/CD configuration if present
+
+Produce a project identity block:
+
+1. **name** — the project's canonical name (from package manifest, not directory name)
+2. **description** — concise summary of what the project does (2-3 sentences max)
+3. **core_value** — single sentence: why does this project exist? What value does it provide?
+4. **target_users** — who uses this? (e.g., "TypeScript developers", "DevOps engineers", "data scientists")
+5. **constraints** — each with `type` and `description`:
+   - Runtime constraints (Node.js version, browser support, etc.)
+   - Language constraints (TypeScript strict mode, ESM-only, etc.)
+   - Compatibility constraints (API stability, backward compat, etc.)
+6. **scope_boundaries**:
+   - `in`: what the project explicitly does
+   - `out`: what the project explicitly does not do (deferred or excluded)
+7. **goals** — each with `id`, `description`, and optional `success_criteria` array
+   - Only include goals evidenced by the codebase (README roadmap, issues, TODO markers)
+8. **status** — one of: inception, planning, development, maintenance, complete
+   - Infer from: version maturity, commit recency, test coverage, presence of CI
+9. **repository** — repository URL if discoverable from package manifest or git remote
+10. **stack** — primary technology choices only (language, framework, key libraries — not every dependency)
+
+## Required Output Schema
+
+You MUST produce JSON conforming exactly to this schema. Every required field must be present.
+
+```json
+{{ output_schema }}
+```

package/templates/requirements-gatherer/task.md

@@ -0,0 +1,90 @@
+## Project Identity
+
+**Name:** {{ project.name }}
+**Description:** {{ project.description }}
+**Core Value:** {{ project.core_value }}
+
+### Target Users
+{% for user in project.target_users %}
+- {{ user }}
+{% endfor %}
+
+### Constraints
+{% for constraint in project.constraints %}
+- [{{ constraint.type }}] {{ constraint.description }}
+{% endfor %}
+
+### Scope Boundaries
+
+**In scope:**
+{% for item in project.scope_boundaries.in %}
+- {{ item }}
+{% endfor %}
+
+**Out of scope:**
+{% for item in project.scope_boundaries.out %}
+- {{ item }}
+{% endfor %}
+
+### Goals
+{% for goal in project.goals %}
+- **{{ goal.id }}**: {{ goal.description }}
+  {% for criterion in goal.success_criteria %}- {{ criterion }}
+  {% endfor %}
+{% endfor %}
+
+{% if vision %}
+## Original Vision
+
+{{ vision }}
+{% endif %}
+
+## Instructions
+
+Derive requirements from the project identity above. Produce a comprehensive but proportionate set of requirements covering what the system must do (functional), quality attributes it must exhibit (non-functional), hard limits it must respect (constraint), and external connections it must support (integration).
+
+### For each requirement, provide:
+
+1. **id** — unique, formatted as REQ-NNN (zero-padded three-digit suffix)
+2. **description** — clear statement of what is required
+3. **type** — one of: `functional`, `non-functional`, `constraint`, `integration`
+4. **status** — set to `"proposed"` for all
+5. **priority** — MoSCoW: `must`, `should`, `could`, `wont`
+6. **acceptance_criteria** — array of specific, verifiable statements
+7. **source** — set to `"agent"` for all
+8. **depends_on** — array of other requirement IDs this depends on (empty array if none)
+
+### Priority guidance
+
+- **must**: the project fails without this — directly tied to core_value and essential goals
+- **should**: important for target users but the project could ship a minimal version without it
+- **could**: enhances the experience but is clearly secondary
+- **wont**: explicitly excluded — derive these from scope_boundaries.out
+
+### Coverage expectations
+
+- Every goal should map to at least one "must" requirement
+- Every constraint should appear as a "constraint" type requirement
+- Include at least one non-functional requirement for each quality attribute the project implies (performance, security, usability, reliability, etc. — only those that are relevant)
+- Include "wont" requirements for major items in scope_boundaries.out
+
+### Output format
+
+Produce a single JSON object with a `requirements` array:
+
+```json
+{
+  "requirements": [
+    {
+      "id": "REQ-NNN",
+      "description": "string",
+      "type": "functional",
+      "status": "proposed",
+      "priority": "must",
+      "acceptance_criteria": ["string"],
+      "source": "agent",
+      "depends_on": []
+    }
+  ]
+}
+```

package/templates/researcher/task.md

@@ -0,0 +1,26 @@
+## Research Request
+
+**Gap:** {{ gap.id }} — {{ gap.description }}
+
+## Questions
+
+{% for q in research_questions %}
+{{ loop.index }}. {{ q }}
+{% endfor %}
+
+## Instructions
+
+For each question:
+1. Answer based on known software engineering patterns, best practices, and established solutions
+2. Rate your confidence: `high` (well-known, widely used), `medium` (established but context-dependent), `low` (best guess)
+3. List sources where possible — documentation, known projects, pattern names
+
+Also identify applicable patterns and concrete recommendations.
+
+## Required Output Schema
+
+You MUST produce JSON conforming exactly to this schema. Every required field must be present.
+
+```json
+{{ output_schema }}
+```