gsdd-cli 0.18.4 → 0.19.0

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

@@ -1,31 +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.
+**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

@@ -1,57 +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
+# 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

package/distilled/templates/research/features.md

@@ -1,23 +1,23 @@
-# FEATURES.md — Feature Landscape
-
-## Table Stakes
-Features users expect. Without them, your product feels broken.
-
-- [ ] [feature] — [why it's expected]
-- [ ] [feature] — [why it's expected]
-
-## Differentiators
-Features that set you apart from competitors.
-
-- [ ] [feature] — [what makes this unique]
-- [ ] [feature] — [competitive advantage]
-
-## Anti-Features
-Things to deliberately NOT build. Complexity traps.
-
-- [ ] [feature to avoid] — [why: complexity trap / scope creep / premature optimization]
-- [ ] [feature to avoid] — [why]
-
-## Sources
-- [Competitor 1] — [what they do well / poorly]
-- [Competitor 2] — [what they do well / poorly]
+# FEATURES.md — Feature Landscape
+
+## Table Stakes
+Features users expect. Without them, your product feels broken.
+
+- [ ] [feature] — [why it's expected]
+- [ ] [feature] — [why it's expected]
+
+## Differentiators
+Features that set you apart from competitors.
+
+- [ ] [feature] — [what makes this unique]
+- [ ] [feature] — [competitive advantage]
+
+## Anti-Features
+Things to deliberately NOT build. Complexity traps.
+
+- [ ] [feature to avoid] — [why: complexity trap / scope creep / premature optimization]
+- [ ] [feature to avoid] — [why]
+
+## Sources
+- [Competitor 1] — [what they do well / poorly]
+- [Competitor 2] — [what they do well / poorly]

package/distilled/templates/research/pitfalls.md

@@ -1,46 +1,46 @@
-# Pitfalls Research Template
-
-Use when researching common mistakes and gotchas for a domain or technology.
-
-Write to: `.planning/research/PITFALLS.md`
-
----
-
-```markdown
-# Pitfalls
-
-**Domain**: [what we're building]
-**Researched**: [date]
-
-## Pitfall 1: [Name]
-
-**What goes wrong**: [description]
-**Why it happens**: [root cause]
-**How to avoid**: [prevention strategy]
-**Warning signs**: [how to detect early]
-
-## Pitfall 2: [Name]
-
-**What goes wrong**: [description]
-**Why it happens**: [root cause]
-**How to avoid**: [prevention strategy]
-**Warning signs**: [how to detect early]
-
-## Pitfall 3: [Name]
-
-**What goes wrong**: [description]
-**Why it happens**: [root cause]
-**How to avoid**: [prevention strategy]
-**Warning signs**: [how to detect early]
-
----
-*These pitfalls should inform verification criteria in the roadmap.*
-```
-
-## Guidelines
-
-- **Be specific to the domain** — not generic advice like "write tests"
-- **Warning signs** are crucial — they let you catch problems early
-- **Prevention strategies** should be actionable, not vague
-- 3-5 pitfalls is the sweet spot — more than 5 and none get remembered
-- **Link to phases**: note which roadmap phase should address each pitfall
+# Pitfalls Research Template
+
+Use when researching common mistakes and gotchas for a domain or technology.
+
+Write to: `.planning/research/PITFALLS.md`
+
+---
+
+```markdown
+# Pitfalls
+
+**Domain**: [what we're building]
+**Researched**: [date]
+
+## Pitfall 1: [Name]
+
+**What goes wrong**: [description]
+**Why it happens**: [root cause]
+**How to avoid**: [prevention strategy]
+**Warning signs**: [how to detect early]
+
+## Pitfall 2: [Name]
+
+**What goes wrong**: [description]
+**Why it happens**: [root cause]
+**How to avoid**: [prevention strategy]
+**Warning signs**: [how to detect early]
+
+## Pitfall 3: [Name]
+
+**What goes wrong**: [description]
+**Why it happens**: [root cause]
+**How to avoid**: [prevention strategy]
+**Warning signs**: [how to detect early]
+
+---
+*These pitfalls should inform verification criteria in the roadmap.*
+```
+
+## Guidelines
+
+- **Be specific to the domain** — not generic advice like "write tests"
+- **Warning signs** are crucial — they let you catch problems early
+- **Prevention strategies** should be actionable, not vague
+- 3-5 pitfalls is the sweet spot — more than 5 and none get remembered
+- **Link to phases**: note which roadmap phase should address each pitfall

package/distilled/templates/research/stack.md

@@ -1,45 +1,45 @@
-# Stack Research Template
-
-Use when researching the technology stack for a project or phase.
-
-Write to: `.planning/research/STACK.md`
-
----
-
-```markdown
-# Stack Research
-
-**Domain**: [what we're building]
-**Researched**: [date]
-
-## Recommended Stack
-
-| Library/Tool | Version | Purpose | Why This One |
-|-------------|---------|---------|--------------|
-| [name] | [ver] | [what it does] | [why it's the right choice] |
-| [name] | [ver] | [what it does] | [why it's the right choice] |
-
-## Alternatives Considered
-
-| Recommended | Alternative | Why Not |
-|-------------|------------|---------|
-| [choice] | [option] | [tradeoff] |
-
-## Don't Hand-Roll
-
-Problems that look simple but have battle-tested solutions:
-
-| Problem | Don't Build | Use Instead | Why |
-|---------|------------|-------------|-----|
-| [problem] | [custom solution] | [library] | [edge cases you'd miss] |
-
----
-*Confidence: [HIGH/MEDIUM/LOW]*
-```
-
-## Guidelines
-
-- **Specific versions** — not "latest", give actual numbers
-- **"Why This One"** matters more than "What It Does"
-- **Don't Hand-Roll** is the highest-value section — prevents wasted effort on solved problems
-- Keep to ~30-40 lines when filled out
+# Stack Research Template
+
+Use when researching the technology stack for a project or phase.
+
+Write to: `.planning/research/STACK.md`
+
+---
+
+```markdown
+# Stack Research
+
+**Domain**: [what we're building]
+**Researched**: [date]
+
+## Recommended Stack
+
+| Library/Tool | Version | Purpose | Why This One |
+|-------------|---------|---------|--------------|
+| [name] | [ver] | [what it does] | [why it's the right choice] |
+| [name] | [ver] | [what it does] | [why it's the right choice] |
+
+## Alternatives Considered
+
+| Recommended | Alternative | Why Not |
+|-------------|------------|---------|
+| [choice] | [option] | [tradeoff] |
+
+## Don't Hand-Roll
+
+Problems that look simple but have battle-tested solutions:
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|------------|-------------|-----|
+| [problem] | [custom solution] | [library] | [edge cases you'd miss] |
+
+---
+*Confidence: [HIGH/MEDIUM/LOW]*
+```
+
+## Guidelines
+
+- **Specific versions** — not "latest", give actual numbers
+- **"Why This One"** matters more than "What It Does"
+- **Don't Hand-Roll** is the highest-value section — prevents wasted effort on solved problems
+- Keep to ~30-40 lines when filled out

package/distilled/templates/research/summary.md

@@ -1,67 +1,67 @@
-# Research Summary
-
-**Date:** [YYYY-MM-DD]
-**Topic:** [Domain/feature area]
-**Milestone context:** [greenfield | subsequent]
-
-## Executive Summary (5-10 bullets)
-- [What we learned, in actionable terms — one concrete insight per bullet]
-
-## Confidence Assessment
-
-| Area | Confidence | Rationale |
-|------|-----------|-----------|
-| Stack choices | ✅ verified / ⚠️ likely / ❓ uncertain | [why] |
-| Feature set | ✅ verified / ⚠️ likely / ❓ uncertain | [why] |
-| Architecture pattern | ✅ verified / ⚠️ likely / ❓ uncertain | [why] |
-| Key pitfalls | ✅ verified / ⚠️ likely / ❓ uncertain | [why] |
-
-## Recommendations (Prescriptive)
-
-For each recommendation, include confidence and the evidence.
-
-1. Recommendation: [Use X / Avoid Y]
-   - Confidence: [verified | likely | uncertain]
-   - Why: [short rationale]
-   - Evidence: [URL(s)]
-   - Counterpoints / tradeoffs: [what would change the decision]
-
-## Non-Goals / Anti-Features
-- [What we explicitly will not do in v1, and why — grounded in research findings]
-
-## Pitfalls To Avoid
-- [Concrete mistakes teams make in this domain — phase-mapped where possible]
-
-## Open Questions (Blockers)
-- [What must be decided before planning can proceed]
-
-## Implications for Roadmap
-
-This section is the critical handoff from research to ROADMAP.md. The roadmapper reads this.
-
-### Suggested Phase Structure
-Derived from architecture build order + pitfall avoidance priorities:
-
-| Phase | Focus | Rationale |
-|-------|-------|-----------|
-| Phase 1 | [Foundation: e.g., data model + auth] | [why this must come first — dependency or risk] |
-| Phase 2 | [Core: e.g., primary user workflow] | [what unblocks after Phase 1] |
-| Phase 3 | [Integration: e.g., external services] | [why deferred — complexity or dependency] |
-| Phase N | [Polish / edge cases] | [why last] |
-
-### Research Flags (Phase-Level)
-These are signals for the planner — which phases need deeper domain research vs standard patterns:
-
-| Phase | Flag | Reason |
-|-------|------|--------|
-| Phase 1 | ⚠️ Needs deeper research | [e.g., "auth pattern depends on regulatory context"] |
-| Phase 2 | ✅ Standard pattern | [e.g., "CRUD with established library — no surprises"] |
-| Phase N | ❓ Uncertain | [e.g., "real-time sync has multiple viable approaches"] |
-
-## Sources
-
-| Claim | URL | Accessed |
-|-------|-----|---------|
-| [Stack recommendation] | [URL] | [YYYY-MM-DD] |
-| [Architecture pattern] | [URL] | [YYYY-MM-DD] |
-| [Pitfall] | [URL] | [YYYY-MM-DD] |
+# Research Summary
+
+**Date:** [YYYY-MM-DD]
+**Topic:** [Domain/feature area]
+**Milestone context:** [greenfield | subsequent]
+
+## Executive Summary (5-10 bullets)
+- [What we learned, in actionable terms — one concrete insight per bullet]
+
+## Confidence Assessment
+
+| Area | Confidence | Rationale |
+|------|-----------|-----------|
+| Stack choices | ✅ verified / ⚠️ likely / ❓ uncertain | [why] |
+| Feature set | ✅ verified / ⚠️ likely / ❓ uncertain | [why] |
+| Architecture pattern | ✅ verified / ⚠️ likely / ❓ uncertain | [why] |
+| Key pitfalls | ✅ verified / ⚠️ likely / ❓ uncertain | [why] |
+
+## Recommendations (Prescriptive)
+
+For each recommendation, include confidence and the evidence.
+
+1. Recommendation: [Use X / Avoid Y]
+   - Confidence: [verified | likely | uncertain]
+   - Why: [short rationale]
+   - Evidence: [URL(s)]
+   - Counterpoints / tradeoffs: [what would change the decision]
+
+## Non-Goals / Anti-Features
+- [What we explicitly will not do in v1, and why — grounded in research findings]
+
+## Pitfalls To Avoid
+- [Concrete mistakes teams make in this domain — phase-mapped where possible]
+
+## Open Questions (Blockers)
+- [What must be decided before planning can proceed]
+
+## Implications for Roadmap
+
+This section is the critical handoff from research to ROADMAP.md. The roadmapper reads this.
+
+### Suggested Phase Structure
+Derived from architecture build order + pitfall avoidance priorities:
+
+| Phase | Focus | Rationale |
+|-------|-------|-----------|
+| Phase 1 | [Foundation: e.g., data model + auth] | [why this must come first — dependency or risk] |
+| Phase 2 | [Core: e.g., primary user workflow] | [what unblocks after Phase 1] |
+| Phase 3 | [Integration: e.g., external services] | [why deferred — complexity or dependency] |
+| Phase N | [Polish / edge cases] | [why last] |
+
+### Research Flags (Phase-Level)
+These are signals for the planner — which phases need deeper domain research vs standard patterns:
+
+| Phase | Flag | Reason |
+|-------|------|--------|
+| Phase 1 | ⚠️ Needs deeper research | [e.g., "auth pattern depends on regulatory context"] |
+| Phase 2 | ✅ Standard pattern | [e.g., "CRUD with established library — no surprises"] |
+| Phase N | ❓ Uncertain | [e.g., "real-time sync has multiple viable approaches"] |
+
+## Sources
+
+| Claim | URL | Accessed |
+|-------|-----|---------|
+| [Stack recommendation] | [URL] | [YYYY-MM-DD] |
+| [Architecture pattern] | [URL] | [YYYY-MM-DD] |
+| [Pitfall] | [URL] | [YYYY-MM-DD] |