gsdd-cli 0.1.0

package/distilled/templates/codebase/conventions.md

@@ -0,0 +1,193 @@
+# Codebase Conventions
+
+**Analysis Date:** [YYYY-MM-DD]
+
+<guidelines>
+- This document is durable intent (rules/patterns), not a directory dump.
+- Be prescriptive. If 80%+ of the codebase follows a pattern, document it as a rule ("Use X"), not as a survey ("Sometimes X").
+- Every non-trivial claim must include at least one concrete file path example.
+- Prefer "how to do it here" over general best practices.
+- Capture testing and mocking boundaries explicitly ("what NOT to mock"). Missing boundaries cause broken tests and slow CI.
+- Capture external integration patterns (webhook verification, auth session management). Missing these causes security vulnerabilities.
+</guidelines>
+
+## Naming Patterns
+
+Files:
+- [Pattern observed]
+
+Functions:
+- [Pattern observed]
+
+Variables:
+- [Pattern observed]
+
+Types:
+- [Pattern observed]
+
+## Code Style
+
+Formatting:
+- Tool: [Tool used]
+- Key settings: [Key settings]
+
+Linting:
+- Tool: [Tool used]
+- Key rules: [Key rules]
+
+## Import Organization
+
+Order:
+1. [First group]
+2. [Second group]
+3. [Third group]
+
+Path aliases:
+- [Aliases used]
+
+## Error Handling
+
+Patterns:
+- [How errors are handled]
+- Examples: `[file paths]`
+
+## Logging
+
+Framework:
+- [Tool or "console"]
+
+Patterns:
+- [When/how to log]
+- Examples: `[file paths]`
+
+## Module / Function Design
+
+Function size:
+- [Guidelines]
+
+Parameters:
+- [Pattern]
+
+Return values:
+- [Pattern]
+
+Exports:
+- [Pattern]
+
+## Convention Adoption Rates
+
+For each major convention documented above, estimate adoption rate using grep-counting (count occurrences in production source files, exclude `node_modules`, `vendor`, generated files). Use the format `~N% (stable|rising|declining)`.
+
+- Pattern requires ≥5 occurrences to estimate; below that, write "prevalence unknown — seen in multiple files."
+- Trend signal: stable = consistent across file age, rising = newer files adopt more, declining = older files adopt more.
+
+Examples:
+- Constructor injection: `~84% (declining)` — 37 of 44 service classes; newer files use factory functions
+- camelCase exports: `~100% (stable)` — enforced by lint rule, zero violations found
+- Inline error handling: `~62% (rising)` — 18 of 29 handlers; recent PRs consistently use this
+
+Replace examples with findings from this codebase.
+
+## Testing And Mocking (High-Leverage)
+
+Test types used:
+- Unit: [yes/no] (runner: [tool]) - examples: `[file paths]`
+- Integration: [yes/no] - examples: `[file paths]`
+- E2E: [yes/no] - examples: `[file paths]`
+
+Where tests live:
+- Unit tests: `[path pattern]`
+- Integration tests: `[path pattern]`
+- E2E tests: `[path pattern]`
+
+Fixtures and factories:
+- Where fixtures live: `[path pattern]`
+- Preferred factory pattern: [pattern]
+
+Mocking boundaries (explicit):
+- Do mock: [what is safe to mock here]
+- Do NOT mock: [what must remain real]
+- Why: [rationale grounded in this codebase]
+- Examples: `[file paths]`
+
+External calls:
+- Network calls in tests: [allowed/blocked]
+- How HTTP is stubbed: [pattern] - examples: `[file paths]`
+- DB usage in tests: [pattern] - examples: `[file paths]`
+
+CI reliability rules:
+- Timeouts: [standard value if any]
+- Flake policy: [rerun policy or "none"]
+- Test parallelism constraints: [if any]
+
+<good_examples>
+Example (good):
+- "All HTTP clients must be injected via `src/lib/http/client.ts` and mocked via `test/utils/mockHttp.ts` (do NOT mock `fetch` directly). See `src/services/billing.ts` and `test/services/billing.test.ts`."
+- "Integration tests use a real Postgres via Docker Compose. Do NOT mock DB queries; instead use `test/fixtures/dbSeed.ts`. See `test/integration/users.test.ts`."
+
+Example (bad):
+- "We use Jest and sometimes integration tests." (no paths, no boundaries, no rules)
+</good_examples>
+
+## External Integration Patterns (Security-Critical)
+
+Capture these only if external integrations exist. Missing these causes subtle security bugs.
+
+### Webhook Verification
+- Webhook endpoints: `[paths]`
+- Signature verification method: [HMAC-SHA256 / provider-specific / none]
+- Where verification happens: `[file path]` (middleware? route handler?)
+- Verified before or after parsing payload: [before — always verify raw body]
+- Do NOT: parse JSON before verifying signature (timing attacks)
+- Examples: `[file paths for webhook handlers]`
+
+### Authentication and Session Management
+- Auth provider: [JWT / session cookie / OAuth / API key / none]
+- Token storage (client): [httpOnly cookie / localStorage / memory]
+- Token storage (server): [Redis / DB / stateless]
+- Refresh logic: [how tokens are refreshed, where that code lives]
+- Where auth is enforced: [middleware path / per-route / both]
+- Protected vs public routes: [pattern or file]
+- Do NOT: store tokens in localStorage for sensitive apps (XSS risk)
+- Examples: `[file paths for auth middleware]`
+
+### Environment Configuration
+- Config loading: `[file path]` (e.g., `src/config/index.ts`)
+- Environment-specific overrides: [dev/staging/prod distinction]
+- Secrets access pattern: [env var / secrets manager / vault]
+- Do NOT: hardcode secrets; do NOT commit `.env` files
+- Examples: `[file paths]`
+
+### Observability Hooks
+- Request logging: [tool + where it's configured]
+- Error tracking: [tool + integration file path]
+- Performance monitoring: [tool + integration point]
+- Health check endpoint: `[path]` (e.g., `/health`)
+- Examples: `[file paths]`
+
+<good_examples>
+Example (good):
+- "Stripe webhooks are verified via `src/webhooks/stripe.ts:verifyStripeSignature()` using the raw request body before JSON parsing. Do NOT route Stripe events through the JSON body parser middleware. See `src/middleware/webhooks.ts`."
+- "Auth tokens are httpOnly cookies (not localStorage). Refresh happens via `src/auth/refresh.ts` called by the global axios interceptor. Token expiry = 15min access, 7-day refresh. See `src/lib/http.ts`."
+- "All secrets come from env vars loaded via `src/config/env.ts`. Never read `process.env` directly outside that file. Dev/staging/prod configs are in `.env.example`, `.env.staging`, `.env.production` (secrets redacted, committed)."
+
+Example (bad):
+- "We use JWT and have some webhooks." (no paths, no security rules, no boundaries)
+</good_examples>
+
+## Golden Files
+
+Identify 3–5 files that best exemplify this codebase's conventions. Selection algorithm: highest density of documented conventions in production feature files (not scaffolding, not generated code, not test files).
+
+Format: `file path — what makes it a good example`
+
+- `[path/to/file.ts]` — [which conventions it demonstrates, e.g., "named exports, constructor injection, custom error class, full test coverage"]
+- `[path/to/file.ts]` — [conventions it demonstrates]
+- `[path/to/file.ts]` — [conventions it demonstrates]
+
+If no single file exemplifies multiple conventions, list the best per-category file instead.
+
+---
+
+*Convention analysis: [date]*
+

package/distilled/templates/codebase/stack.md

@@ -0,0 +1,96 @@
+# Codebase Stack
+
+**Analysis Date:** [YYYY-MM-DD]
+
+<guidelines>
+- List versions only when they matter (compatibility, breaking changes, reproducibility).
+- Prefer commands and sources of truth (package.json, lockfiles, tool config) over memory.
+- Capture the minimum needed for another agent to run, test, and ship changes safely.
+- Include concrete commands and file paths.
+</guidelines>
+
+## Languages
+
+Primary:
+- [Language] [Version if relevant] - used in: `[paths]`
+
+Secondary:
+- [Language] [Version if relevant] - used in: `[paths]`
+
+## Runtime
+
+Environment:
+- [Runtime] [Version if relevant]
+
+Package manager:
+- [Manager] [Version if relevant]
+- Lockfile: [present/missing] - `[path]`
+
+## Frameworks And Tooling
+
+Core framework(s):
+- [Framework] [Version if relevant] - purpose: [purpose]
+
+Testing:
+- [Tool] [Version if relevant] - purpose: [purpose]
+
+Build / dev:
+- [Tool] [Version if relevant] - purpose: [purpose]
+
+Lint / format:
+- [Tool] - config: `[path]`
+
+## Key Dependencies (Only What Drives Architecture)
+
+Critical libraries:
+- [Package] - why it matters: [reason] - examples: `[paths]`
+
+Infra/observability:
+- [Package] - purpose: [reason] - config: `[paths]`
+
+## Must-Know Packages
+
+Flag 3–5 packages that new contributors must understand before making changes. These are not necessarily the most-used packages — they are the ones where misuse causes hard-to-debug problems.
+
+Each entry: `package-name — why it's critical — risk: low|medium|high — common mistake: what goes wrong`
+
+Risk levels: low (causes build errors — immediately visible), medium (causes runtime bugs — visible in testing), high (causes data corruption or silent failures — hard to detect).
+
+- `[package]` — [why critical] — risk: [level] — common mistake: [what goes wrong]
+- `[package]` — [why critical] — risk: [level] — common mistake: [what goes wrong]
+- `[package]` — [why critical] — risk: [level] — common mistake: [what goes wrong]
+
+## How To Run
+
+Install:
+- Command(s): `[commands]`
+
+Dev:
+- Command(s): `[commands]`
+
+Test:
+- Command(s): `[commands]`
+
+Build:
+- Command(s): `[commands]`
+
+## Configuration
+
+Env:
+- How configured: [dotenv, env vars, config files]
+- Key config files: `[paths]`
+
+CI/CD:
+- CI location: `[path]`
+- Main checks: [list]
+
+<good_examples>
+Example (good):
+- "Node 20, pnpm. Install: `pnpm i`. Tests: `pnpm test` (Vitest) + `pnpm test:e2e` (Playwright). Formatting: Prettier (`.prettierrc`). Lint: ESLint (`eslint.config.mjs`)."
+- "DB migrations run via `pnpm db:migrate` (see `package.json` scripts)."
+</good_examples>
+
+---
+
+*Stack analysis: [date]*
+

package/distilled/templates/delegates/mapper-arch.md

@@ -0,0 +1,26 @@
+**Role contract:** Read `.planning/templates/roles/mapper.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
+
+Map the architecture and structure of this codebase. Read key source files to understand component boundaries, data flow, and patterns.
+
+Write ARCHITECTURE.md to `.planning/codebase/` using the template at `.planning/templates/codebase/architecture.md`.
+
+Include:
+- Major components and their responsibilities (what belongs in each, what doesn't)
+- Data flow direction (not just "they communicate" — which way does data move)
+- "Change Routing" table: where to add new code by change type (new endpoint? new model? new UI component?)
+- Key architectural patterns used (e.g., event-driven, layered, modular monolith)
+- Golden files per layer: for each major layer, the single most-imported file (highest inbound import count = most stable, most understood); use import frequency as the signal, not judgment
+
+**Anti-staleness:** Do NOT include static directory trees or full file inventories. DO include file paths for key components, entry points, and architectural boundaries (e.g., `src/services/user.ts`) -- downstream agents navigate directly to files.
+
+<quality_gate>
+- [ ] Components have clear responsibility boundaries
+- [ ] Data flow direction is explicit
+- [ ] Change Routing table is populated (where to add new code by type)
+- [ ] Hard-to-reverse architectural decisions flagged
+- [ ] Golden files table populated with at least one file per major layer
+</quality_gate>
+
+Write to: `.planning/codebase/ARCHITECTURE.md`
+Return: 3-5 sentence summary to the Orchestrator when done.
+Guardrails: Max Agent Hops = 3. No static directory dumps.

package/distilled/templates/delegates/mapper-concerns.md

@@ -0,0 +1,27 @@
+**Role contract:** Read `.planning/templates/roles/mapper.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
+
+Map the technical debt, security concerns, and risks in this codebase.
+
+**Security check first (hard stop):** Follow the Hard stop directive in `.planning/templates/roles/mapper.md` — grep for secrets before writing anything. If found: STOP and report to Orchestrator immediately.
+
+If no secrets found, write CONCERNS.md to `.planning/codebase/` using the template at `.planning/templates/codebase/concerns.md`.
+
+Include:
+- Known bugs or fragile areas (with file references where possible)
+- Security vulnerabilities or missing validations
+- Performance bottlenecks
+- Missing test coverage for critical paths
+- Deprecated or end-of-life dependencies
+- Downstream impact ranking: top 3 concerns ranked by how much future work they block (concerns blocking multiple change-routing rows from ARCHITECTURE.md rank highest, not just by severity)
+
+<quality_gate>
+- [ ] Secret scan completed and result reported
+- [ ] Concerns are specific (file references, not vague "some places")
+- [ ] Severity assigned per concern: critical / moderate / minor
+- [ ] Deprecated dependencies listed with EOL dates if known
+- [ ] Downstream impact table ranks at least top 3 concerns with Blocks column populated
+</quality_gate>
+
+Write to: `.planning/codebase/CONCERNS.md`
+Return: 3-5 sentence summary to the Orchestrator when done. If secrets found, STOP and report immediately.
+Guardrails: Max Agent Hops = 3. Hard stop on secrets.

package/distilled/templates/delegates/mapper-quality.md

@@ -0,0 +1,28 @@
+**Role contract:** Read `.planning/templates/roles/mapper.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
+
+Map the conventions and quality patterns of this codebase. Read existing tests, lint config, and code samples.
+
+Write CONVENTIONS.md to `.planning/codebase/` using the template at `.planning/templates/codebase/conventions.md`.
+
+Include:
+- Naming patterns (files, functions, variables, exports)
+- Code style rules enforced by lint/format config
+- Testing and mocking boundaries — explicit "Do mock" / "Do NOT mock" rules with examples
+- External integration patterns: webhook signature verification, auth session management, environment config
+- CI reliability rules (what must pass before merge)
+- Convention adoption rates: for each major convention, estimate `~N% (stable|rising|declining)` using grep-counting (≥5 occurrences required; below that write "prevalence unknown — seen in multiple files")
+- Golden files: 2–3 production files with the highest density of documented conventions (not scaffolding, not generated, not tests); format: `file path — which conventions it demonstrates`
+
+**Anti-staleness:** Do NOT enumerate test files or list every convention observed. Document rules and patterns: the invariants, not the inventory.
+
+<quality_gate>
+- [ ] Mocking boundaries are explicit ("Do mock: X" / "Do NOT mock: Y")
+- [ ] External integration security rules included (webhook, auth, env config)
+- [ ] Rules are actionable ("always do X"), not descriptive ("the codebase uses X")
+- [ ] At least one convention has a quantified adoption rate (e.g., `~N% (stable|rising|declining)`)
+- [ ] Golden files section lists at least 2 files with rationale
+</quality_gate>
+
+Write to: `.planning/codebase/CONVENTIONS.md`
+Return: 3-5 sentence summary to the Orchestrator when done.
+Guardrails: Max Agent Hops = 3. Rules not inventories.

package/distilled/templates/delegates/mapper-tech.md

@@ -0,0 +1,25 @@
+**Role contract:** Read `.planning/templates/roles/mapper.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
+
+Map the technology stack of this codebase. Read package manifests, lockfiles, and entry points.
+
+Write STACK.md to `.planning/codebase/` using the template at `.planning/templates/codebase/stack.md`.
+
+Include:
+- Languages and runtimes (with versions)
+- Frameworks and key libraries (10-20 most important, not the full lockfile)
+- Infrastructure and deployment tooling
+- For each package: why it matters to this project (not just what it is)
+- Must-know packages: 3–5 packages where misuse causes the hardest-to-debug problems; include risk index (low/medium/high) and the common mistake to avoid
+
+**Anti-staleness:** Do NOT dump the full lockfile or dependency tree. Include only packages with architectural significance and note why they matter.
+
+<quality_gate>
+- [ ] 10-20 packages listed with version + rationale (not a lockfile dump)
+- [ ] Build/deploy tooling included
+- [ ] Any deprecated or risky dependencies flagged
+- [ ] Must-know packages section identifies at least 3 packages with risk index (low/medium/high)
+</quality_gate>
+
+Write to: `.planning/codebase/STACK.md`
+Return: 3-5 sentence summary to the Orchestrator when done.
+Guardrails: Max Agent Hops = 3. No static dependency dumps.

package/distilled/templates/delegates/plan-checker.md

@@ -0,0 +1,55 @@
+**Role contract:** Read `.planning/templates/roles/planner.md` before starting. Reuse its planning vocabulary and quality standards, but this wrapper overrides your objective: you are reviewing plans, not authoring them.
+
+You are the fresh-context plan checker for `/gsdd:plan`.
+
+Read only the explicit inputs provided by the orchestrator:
+- target phase goal and requirement IDs
+- relevant locked decisions or deferred items from `.planning/SPEC.md`
+- any relevant phase research file
+- the produced `.planning/phases/*-PLAN.md` file(s)
+
+Do NOT inherit the planner's hidden reasoning. Treat the current plans as untrusted drafts that must prove they will achieve the phase goal before execution.
+
+Verify these dimensions:
+- `requirement_coverage`: every phase requirement is covered by at least one concrete task
+- `task_completeness`: every executable task has files, action, verify, and done fields. Additionally check verify quality:
+  - **Runnable?** Does `<verify>` contain at least one command that an executor can run programmatically (e.g., a shell command, test runner invocation, curl request)? If ALL verify items are observational text with no runnable command -> `blocker`.
+  - **Fast?** Do verify commands complete quickly? Flag full E2E suites (playwright, cypress, selenium) without a faster smoke test -> `warning`. Flag watch-mode flags (`--watchAll`, `--watch`) -> `blocker`. Flag arbitrary delays > 30s -> `warning`.
+  - **Ordered?** If a verify command references a test file, does an earlier task in the plan create that file? If the referenced file has no prior task producing it -> `blocker`.
+- `dependency_correctness`: ordering, dependencies, and plan structure are coherent
+- `key_link_completeness`: important wiring/integration links are planned, not just isolated artifacts
+- `scope_sanity`: plans are sized so an executor can complete them without context collapse
+- `must_have_quality`: success criteria and must-haves are specific, observable, and reflected in tasks
+- `context_compliance`: locked decisions are honored and deferred ideas stay out of scope
+
+Return JSON only as a single object with this shape:
+
+```json
+{
+  "status": "passed",
+  "summary": "One sentence overall assessment",
+  "issues": [
+    {
+      "dimension": "requirement_coverage",
+      "severity": "blocker",
+      "description": "What is wrong",
+      "plan": "01-PLAN",
+      "task": "1-02",
+      "fix_hint": "Specific revision instruction"
+    }
+  ]
+}
+```
+
+Rules:
+- Status must be either `"passed"` or `"issues_found"`.
+- Use `"status": "passed"` only when no blockers remain. Warnings may still be listed.
+- Use `"status": "issues_found"` when any blocker exists or when warnings should be surfaced for revision.
+- Keep `fix_hint` targeted. The planner should patch the existing plan, not replan from scratch, unless the issue is fundamental.
+- If there are no issues, return `"issues": []`.
+
+Guardrails:
+- Do NOT write or edit plan files yourself.
+- Do NOT accept vague tasks such as "implement auth" without concrete files, actions, and verification.
+- Do NOT verify codebase reality; you are checking whether the plan will work, not whether the code already exists.
+- Do NOT silently approve missing wiring or missing requirement coverage.

package/distilled/templates/delegates/researcher-architecture.md

@@ -0,0 +1,30 @@
+**Role contract:** Read `.planning/templates/roles/researcher.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
+
+You are researching ONE dimension: how systems in this domain are typically structured.
+
+The Orchestrator has provided you with:
+- Project goal / domain (in your Context)
+- Milestone context: `greenfield` or `subsequent` (in your Context)
+
+**If greenfield:** How are systems in this domain typically structured? What are the major components and boundaries?
+**If subsequent:** How do the target features integrate with existing architecture? What are the integration patterns?
+
+**Research question:** How are systems in this domain typically structured? What are the major components, their boundaries, and the suggested build order?
+
+Your output informs phase structure in ROADMAP.md. Include:
+- Component map: what each component is responsible for
+- Data flow: how information moves between components (direction matters)
+- Suggested build order: which components have dependencies ("Auth must exist before any user-scoped feature")
+- Key decision points: architectural choices that are hard to reverse
+
+<quality_gate>
+- [ ] Components have clear boundaries (what belongs, what doesn't)
+- [ ] Data flow direction explicit (not just "they communicate")
+- [ ] Build order implications documented (what blocks what)
+- [ ] Hard-to-reverse decisions flagged explicitly
+</quality_gate>
+
+Write to: `.planning/research/ARCHITECTURE.md`
+Use template: `.planning/templates/research/architecture.md` (if it exists)
+Return: 3-5 sentence summary of key findings to the Orchestrator when done.
+Guardrails: Max Agent Hops = 3.

package/distilled/templates/delegates/researcher-features.md

@@ -0,0 +1,30 @@
+**Role contract:** Read `.planning/templates/roles/researcher.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
+
+You are researching ONE dimension: what features exist in this domain.
+
+The Orchestrator has provided you with:
+- Project goal / domain (in your Context)
+- Milestone context: `greenfield` or `subsequent` (in your Context)
+
+**If greenfield:** What features do products in this domain have? What's table stakes vs differentiating?
+**If subsequent:** How do the target features typically work? What do users expect as baseline behavior?
+
+**Research question:** What features do products in this domain have? What's table stakes (users leave without it) vs differentiating (competitive advantage) vs anti-feature (actively harmful to include in v1)?
+
+Your output feeds SPEC requirements. Categorize explicitly:
+- **Table Stakes**: Must have or users leave (each with brief why)
+- **Differentiators**: Competitive advantage (each with complexity estimate: low/medium/high)
+- **Anti-features**: Things to deliberately NOT build in v1 (with rationale)
+- Dependencies between features (Feature B requires Feature A)
+
+<quality_gate>
+- [ ] All three categories populated (table stakes / differentiators / anti-features)
+- [ ] Complexity estimate per differentiator (low/medium/high)
+- [ ] Dependencies between features identified
+- [ ] v1 vs v2 recommendation for differentiators
+</quality_gate>
+
+Write to: `.planning/research/FEATURES.md`
+Use template: `.planning/templates/research/features.md` (if it exists)
+Return: 3-5 sentence summary of key findings to the Orchestrator when done.
+Guardrails: Max Agent Hops = 3.

package/distilled/templates/delegates/researcher-pitfalls.md

@@ -0,0 +1,30 @@
+**Role contract:** Read `.planning/templates/roles/researcher.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
+
+You are researching ONE dimension: what goes wrong in projects in this domain.
+
+The Orchestrator has provided you with:
+- Project goal / domain (in your Context)
+- Milestone context: `greenfield` or `subsequent` (in your Context)
+
+**If greenfield:** What do projects in this domain commonly get wrong? Critical mistakes in early decisions?
+**If subsequent:** What are common mistakes when adding the target features to existing projects? Integration anti-patterns?
+
+**Research question:** What do projects in this domain commonly get wrong? What are the critical mistakes that are expensive to fix later?
+
+Your output prevents mistakes in roadmap and planning. For each pitfall:
+- Warning signs: how to detect it early
+- Prevention strategy: specific and actionable ("do X"), not vague ("be careful")
+- Which phase should address it (Phase 1? Phase 3?)
+- Severity: critical (breaks the product) / moderate (slows development) / minor (cleanup later)
+
+<quality_gate>
+- [ ] Pitfalls are specific to THIS domain, not generic advice
+- [ ] Prevention strategies are actionable ("do X"), not vague ("be careful")
+- [ ] Phase mapping included where relevant
+- [ ] Sources cited for non-obvious claims
+</quality_gate>
+
+Write to: `.planning/research/PITFALLS.md`
+Use template: `.planning/templates/research/pitfalls.md` (if it exists)
+Return: 3-5 sentence summary of key findings to the Orchestrator when done.
+Guardrails: Max Agent Hops = 3.

package/distilled/templates/delegates/researcher-stack.md

@@ -0,0 +1,30 @@
+**Role contract:** Read `.planning/templates/roles/researcher.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
+
+You are researching ONE dimension: the technology stack for the project domain.
+
+The Orchestrator has provided you with:
+- Project goal / domain (in your Context)
+- Milestone context: `greenfield` or `subsequent` (in your Context)
+
+**If greenfield:** Research the standard stack for building this domain from scratch.
+**If subsequent:** Research what libraries/tools are needed to ADD the target features to an existing app. Don't re-research the existing system.
+
+**Research question:** What is the current (2025/2026) standard stack for this domain? Which libraries are proven vs risky?
+
+Your output feeds the roadmapper. Be prescriptive:
+- Specific package names with current versions (verify via web search — do NOT rely on training data)
+- Clear rationale for each choice: why this, not the alternatives
+- Explicit "Do NOT use" list with reasons
+- Confidence level per recommendation: ✅ verified (official docs), ⚠️ likely, ❓ uncertain
+
+<quality_gate>
+- [ ] Versions verified against current official docs or registry (not training data)
+- [ ] Every recommendation has a rationale AND a counterpoint (when you'd choose differently)
+- [ ] "What NOT to use" section populated with specific packages and reasons
+- [ ] Confidence level assigned to each recommendation
+</quality_gate>
+
+Write to: `.planning/research/STACK.md`
+Use template: `.planning/templates/research/stack.md` (if it exists)
+Return: 3-5 sentence summary of key findings to the Orchestrator when done.
+Guardrails: Max Agent Hops = 3.

package/distilled/templates/delegates/researcher-synthesizer.md

@@ -0,0 +1,31 @@
+**Role contract:** Read `.planning/templates/roles/synthesizer.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
+
+Synthesize the 4 research files into a single actionable SUMMARY.md.
+
+Read these files (all should exist):
+- `.planning/research/STACK.md`
+- `.planning/research/FEATURES.md`
+- `.planning/research/ARCHITECTURE.md`
+- `.planning/research/PITFALLS.md`
+
+Cross-reference them. Surface conflicts and dependencies between findings. Do NOT do new research — synthesize what exists.
+
+SUMMARY.md MUST include:
+1. **Key Findings** — top 5-7 bullets across all 4 dimensions
+2. **Implications for Roadmap** — suggested phase groupings derived from architecture build order + pitfall avoidance (this is the critical handoff to the roadmapper)
+3. **Research Flags** — which phases need deeper research vs standard patterns
+4. **Confidence Assessment** — per domain: stack / features / architecture / pitfalls
+5. **Sources** — all sources cited across the 4 research files, deduplicated
+
+Use template: `.planning/templates/research/summary.md` (if it exists)
+
+<quality_gate>
+- [ ] "Implications for Roadmap" section populated with phase suggestions
+- [ ] Conflicts between research files surfaced (not hidden)
+- [ ] Confidence levels consistent with what researchers assigned
+- [ ] No new claims introduced (only synthesis)
+</quality_gate>
+
+Write to: `.planning/research/SUMMARY.md`
+Return: 5-7 bullet key findings to the Orchestrator when done.
+Guardrails: Max Agent Hops = 2. Do not do new research — synthesize only.

package/distilled/templates/research/architecture.md

@@ -0,0 +1,57 @@
+# Architecture Research Template
+
+Use when researching system structure and patterns for a project or phase.
+
+Write to: `.planning/research/ARCHITECTURE.md`
+
+---
+
+```markdown
+# Architecture Research
+
+**Domain**: [what we're building]
+**Researched**: [date]
+
+## Recommended Structure
+
+```
+src/
+├── [folder]/        # [purpose]
+├── [folder]/        # [purpose]
+└── [folder]/        # [purpose]
+```
+
+## Key Patterns
+
+### [Pattern Name]
+**What**: [description]
+**When**: [when to use it]
+**Example**:
+```
+[brief code or pseudo-code snippet]
+```
+
+### [Pattern Name]
+**What**: [description]
+**When**: [when to use it]
+
+## Anti-Patterns
+
+- **[Don't do this]**: [why it's bad] → [do this instead]
+- **[Don't do this]**: [why it's bad] → [do this instead]
+
+## Component Boundaries
+
+[Which components talk to which, data flow direction, build order implications]
+
+---
+*Confidence: [HIGH/MEDIUM/LOW]*
+```
+
+## Guidelines
+
+- **Structure** should reflect the actual folder layout you'd create
+- **Patterns** should include real examples, not just names
+- **Anti-patterns** are as valuable as patterns — they prevent common mistakes
+- **Component boundaries** inform phase ordering in the roadmap
+- Keep to ~40-50 lines when filled out