learnship 2.0.11 → 2.1.1

package/templates/context.md

@@ -6,67 +6,242 @@ workflow: discuss-phase
 
 # Phase [N] Context: [Phase Name]
 
-Implementation decisions captured during `discuss-phase [N]`. This file is read by the planner, researcher, and executor — it represents locked user preferences that override default approaches.
+Implementation decisions captured during `discuss-phase [N]`. This file is the primary input for downstream agents — the researcher uses it to know WHAT to investigate, the planner uses it to know WHAT choices are locked.
 
----
+<domain>
+## Phase Boundary
+
+[Clear statement of what this phase delivers — the scope anchor. This comes from ROADMAP.md and is fixed. Discussion clarifies implementation within this boundary.]
+
+</domain>
 
+<decisions>
 ## Implementation Decisions
 
-### Technology Choices
+### [Area 1 that was discussed]
+- **D-01:** [Specific decision made]
+- **D-02:** [Another decision if applicable]
+
+### [Area 2 that was discussed]
+- **D-03:** [Specific decision made]
+
+### [Area 3 that was discussed]
+- **D-04:** [Specific decision made]
+
+### Claude's Discretion
+[Areas where user explicitly said "you decide" — the agent has flexibility here during planning/implementation]
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+[Any particular references, examples, or "I want it like X" moments from discussion. Product references, specific behaviors, interaction patterns.]
 
-*What specific libraries, frameworks, or tools should be used?*
+[If none: "No specific requirements — open to standard approaches"]
 
-- [Decision]: [Choice] — [rationale]
-- [Decision]: [Choice] — [rationale]
+</specifics>
 
-### Architecture Preferences
+<canonical_refs>
+## Canonical References
 
-*How should this be structured? Patterns, layers, component organization?*
+**Downstream agents MUST read these before planning or implementing.**
 
-- [Decision]: [Choice] — [rationale]
+[List every spec, ADR, feature doc, or design doc that defines requirements or constraints for this phase. Use full relative paths so agents can read them directly.]
 
-### Scope Boundaries
+### [Topic area 1]
+- `path/to/spec-or-adr.md` — [What this doc decides/defines that's relevant]
 
-*What's explicitly in scope vs. explicitly deferred?*
+### [Topic area 2]
+- `path/to/feature-doc.md` — [What capability this defines]
 
-**In scope for this phase:**
-- [item]
-- [item]
+[If the project has no external specs: "No external specs — requirements are fully captured in decisions above"]
 
-**Explicitly deferred (do not implement):**
-- [item]
-- [item]
+</canonical_refs>
 
-### UI/UX Decisions
+<code_context>
+## Existing Code Insights
 
-*Visual style, interaction patterns, design direction (if UI work)*
+### Reusable Assets
+- [Component/hook/utility]: [How it could be used in this phase]
 
-- [Decision]: [Choice] — [rationale]
+### Established Patterns
+- [Pattern]: [How it constrains/enables this phase]
 
 ### Integration Points
+- [Where new code connects to existing system]
 
-*How should this phase connect to other phases or existing systems?*
+</code_context>
 
-- [item]: [approach]
+<deferred>
+## Deferred Ideas
 
-### Quality Standards
+[Ideas that came up during discussion but belong in other phases. Captured here so they're not lost, but explicitly out of scope for this phase.]
 
-*Performance targets, error handling approach, test coverage expectations*
+[If none: "None — discussion stayed within phase scope"]
 
-- [item]: [requirement]
+</deferred>
 
 ---
 
-## Open Questions
+*Phase: [padded]-[slug]*
+*Context gathered: [date]*
 
-*Unresolved items — planner should make a reasonable default choice and note it*
+---
 
-- [question]: [status — TBD / will decide during planning / not critical]
+<good_examples>
 
----
+**Example 1: Visual feature (Post Feed)**
+
+```markdown
+# Phase 3: Post Feed - Context
+
+**Gathered:** 2025-01-20
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Display posts from followed users in a scrollable feed. Users can view posts and see engagement counts. Creating posts and interactions are separate phases.
+</domain>
+
+<decisions>
+## Implementation Decisions
 
-## Anti-Patterns to Avoid
+### Layout style
+- Card-based layout, not timeline or list
+- Each card shows: author avatar, name, timestamp, full post content, reaction counts
+- Cards have subtle shadows, rounded corners — modern feel
 
-*Approaches the user explicitly wants to avoid*
+### Loading behavior
+- Infinite scroll, not pagination
+- Pull-to-refresh on mobile
+- New posts indicator at top ("3 new posts") rather than auto-inserting
+
+### Empty state
+- Friendly illustration + "Follow people to see posts here"
+- Suggest 3-5 accounts to follow based on interests
+
+### Claude's Discretion
+- Loading skeleton design
+- Exact spacing and typography
+- Error state handling
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- "I like how Twitter shows the new posts indicator without disrupting your scroll position"
+- Cards should feel like Linear's issue cards — clean, not cluttered
+</specifics>
+
+<canonical_refs>
+## Canonical References
+
+### Feed display
+- `docs/features/social-feed.md` — Feed requirements, post card fields, engagement display rules
+
+### Empty states
+- `docs/design/empty-states.md` — Empty state patterns, illustration guidelines
+</canonical_refs>
+
+<deferred>
+## Deferred Ideas
+
+- Commenting on posts — Phase 5
+- Bookmarking posts — add to backlog
+</deferred>
+```
+
+**Example 2: CLI tool (Database backup)**
+
+```markdown
+# Phase 2: Backup Command - Context
+
+**Gathered:** 2025-01-20
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+CLI command to backup database to local file or S3. Supports full and incremental backups. Restore command is a separate phase.
+</domain>
+
+<decisions>
+## Implementation Decisions
 
-- [anti-pattern]: [reason]
+### Output format
+- JSON for programmatic use, table format for humans
+- Default to table, --json flag for JSON
+- Verbose mode (-v) shows progress, silent by default
+
+### Flag design
+- Short flags for common options: -o (output), -v (verbose), -f (force)
+- Long flags for clarity: --incremental, --compress, --encrypt
+- Required: database connection string (positional or --db)
+
+### Error recovery
+- Retry 3 times on network failure, then fail with clear message
+- --no-retry flag to fail fast
+- Partial backups are deleted on failure (no corrupt files)
+
+### Claude's Discretion
+- Exact progress bar implementation
+- Compression algorithm choice
+- Temp file handling
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- "I want it to feel like pg_dump — familiar to database people"
+- Should work in CI pipelines (exit codes, no interactive prompts)
+</specifics>
+
+<canonical_refs>
+## Canonical References
+
+### Backup CLI
+- `docs/features/backup-restore.md` — Backup requirements, supported backends, encryption spec
+- `docs/decisions/adr-007-cli-conventions.md` — Flag naming, exit codes, output format standards
+</canonical_refs>
+
+<deferred>
+## Deferred Ideas
+
+- Scheduled backups — separate phase
+- Backup rotation/retention — add to backlog
+</deferred>
+```
+
+</good_examples>
+
+<guidelines>
+**This template captures DECISIONS for downstream agents.**
+
+The output should answer: "What does the researcher need to investigate? What choices are locked for the planner?"
+
+**Good content (concrete decisions):**
+- "Card-based layout, not timeline"
+- "Retry 3 times on network failure, then fail"
+- "Group by year, then by month"
+- "JSON for programmatic use, table for humans"
+
+**Bad content (too vague):**
+- "Should feel modern and clean"
+- "Good user experience"
+- "Fast and responsive"
+- "Easy to use"
+
+**After creation:**
+- File lives in phase directory: `.planning/phases/XX-name/{phase_num}-CONTEXT.md`
+- The researcher uses decisions to focus investigation AND reads canonical_refs to know WHAT docs to study
+- The planner uses decisions + research to create executable tasks AND reads canonical_refs to verify alignment
+- Downstream agents should NOT need to ask the user again about captured decisions
+
+**Canonical references:**
+- The `<canonical_refs>` section is MANDATORY. Every CONTEXT.md must have one.
+- If your project has external specs, ADRs, or design docs, list them with full relative paths grouped by topic
+- If ROADMAP.md lists `Canonical refs:` per phase, extract and expand those
+- If no external specs exist, say so explicitly — don't silently omit the section
+</guidelines>

package/templates/discussion-log.md

@@ -0,0 +1,49 @@
+---
+phase: [N]
+slug: [phase-slug]
+areas_discussed: []
+created: [date]
+---
+
+# Phase [N]: [Name] - Discussion Log
+
+> **Audit trail only.** Do not use as input to planning, research, or execution agents.
+> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
+
+**Date:** [ISO date]
+**Phase:** [phase number]-[phase name]
+**Areas discussed:** [comma-separated list]
+
+---
+
+## [Area 1 Name]
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| [Option 1] | [Brief description] | |
+| [Option 2] | [Brief description] | ✓ |
+| [Option 3] | [Brief description] | |
+
+**User's choice:** [Selected option or verbatim free-text response]
+**Notes:** [Any clarifications or rationale provided during discussion]
+
+---
+
+## [Area 2 Name]
+
+...
+
+---
+
+## Claude's Discretion
+
+[Areas delegated to Claude's judgment — list what was deferred and why]
+
+## Deferred Ideas
+
+[Ideas mentioned but not in scope for this phase]
+
+---
+
+*Phase: [padded]-[slug]*
+*Discussion log generated: [date]*

package/templates/security.md

@@ -0,0 +1,61 @@
+---
+phase: {N}
+slug: {phase-slug}
+status: draft
+threats_open: 0
+created: {date}
+---
+
+# Phase {N} — Security
+
+> Per-phase security contract: threat register, accepted risks, and audit trail.
+
+---
+
+## Trust Boundaries
+
+| Boundary | Description | Data Crossing |
+|----------|-------------|---------------|
+| {boundary} | {description} | {data type / sensitivity} |
+
+---
+
+## Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation | Status |
+|-----------|----------|-----------|-------------|------------|--------|
+| T-{N}-01 | {STRIDE category} | {component} | {mitigate / accept / transfer} | {control or reference} | open |
+
+*Status: open · closed*
+*Disposition: mitigate (implementation required) · accept (documented risk) · transfer (third-party)*
+*STRIDE categories: Spoofing · Tampering · Repudiation · Information Disclosure · Denial of Service · Elevation of Privilege*
+
+---
+
+## Accepted Risks Log
+
+| Risk ID | Threat Ref | Rationale | Accepted By | Date |
+|---------|------------|-----------|-------------|------|
+
+*Accepted risks do not resurface in future audit runs.*
+
+*If none: "No accepted risks."*
+
+---
+
+## Security Audit Trail
+
+| Audit Date | Threats Total | Closed | Open | Run By |
+|------------|---------------|--------|------|--------|
+| {YYYY-MM-DD} | {N} | {N} | {N} | {name / agent} |
+
+---
+
+## Sign-Off
+
+- [ ] All threats have a disposition (mitigate / accept / transfer)
+- [ ] Accepted risks documented in Accepted Risks Log
+- [ ] `threats_open: 0` confirmed
+- [ ] `status: verified` set in frontmatter
+
+**Approval:** {pending / verified YYYY-MM-DD}

package/templates/ui-spec.md

@@ -0,0 +1,107 @@
+---
+phase: {N}
+slug: {phase-slug}
+status: draft
+created: {date}
+---
+
+# Phase {N} — UI Design Contract
+
+> Visual and interaction contract for frontend phases. Verified against impeccable standards.
+
+---
+
+## Design System
+
+| Property | Value |
+|----------|-------|
+| Component library | {library or "none"} |
+| Icon library | {library} |
+| Font | {font} |
+| CSS approach | {tailwind / css modules / styled-components / etc.} |
+
+---
+
+## Spacing Scale
+
+Declared values (must be multiples of 4):
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| xs | 4px | Icon gaps, inline padding |
+| sm | 8px | Compact element spacing |
+| md | 16px | Default element spacing |
+| lg | 24px | Section padding |
+| xl | 32px | Layout gaps |
+| 2xl | 48px | Major section breaks |
+| 3xl | 64px | Page-level spacing |
+
+Exceptions: {list any, or "none"}
+
+---
+
+## Typography
+
+| Role | Size | Weight | Line Height |
+|------|------|--------|-------------|
+| Body | {px} | {weight} | {ratio} |
+| Label | {px} | {weight} | {ratio} |
+| Heading | {px} | {weight} | {ratio} |
+| Display | {px} | {weight} | {ratio} |
+
+---
+
+## Color
+
+| Role | Value | Usage |
+|------|-------|-------|
+| Primary | {hex} | Buttons, links, active states |
+| Secondary | {hex} | Supporting actions |
+| Neutral | {hex} | Text, borders, backgrounds |
+| Success | {hex} | Confirmations, positive states |
+| Warning | {hex} | Cautions, pending states |
+| Error | {hex} | Errors, destructive actions |
+
+---
+
+## Key Components
+
+| Component | Spec |
+|-----------|------|
+| {component} | {key constraints: size, padding, border-radius, shadow} |
+
+---
+
+## Interaction Patterns
+
+| Pattern | Behavior |
+|---------|----------|
+| Loading | {skeleton / spinner / progressive} |
+| Empty state | {illustration + CTA / minimal text / guided action} |
+| Error state | {inline / toast / modal / redirect} |
+| Transitions | {duration, easing, what animates} |
+
+---
+
+## Responsive Breakpoints
+
+| Breakpoint | Width | Layout Changes |
+|------------|-------|----------------|
+| Mobile | < 640px | {description} |
+| Tablet | 640-1024px | {description} |
+| Desktop | > 1024px | {description} |
+
+---
+
+## Impeccable Checklist
+
+- [ ] No overused fonts (Inter, Roboto, Arial)
+- [ ] No AI palette (cyan-on-dark, purple-to-blue gradients)
+- [ ] No pure black (#000) or pure white (#fff) — tinted neutrals
+- [ ] No nested cards inside cards
+- [ ] No large rounded icons above every heading
+- [ ] At least one intentional, memorable design decision
+- [ ] Typography has clear visual hierarchy with modular scale
+- [ ] Spacing creates rhythm through variation, not uniformity
+
+**If someone saw this interface and immediately thought AI made it — that is the problem.**