@jamie-tam/forge 6.0.0

package/skills/plan-architecture/templates/db-schema.md

@@ -0,0 +1,81 @@
+# Database Schema
+
+## Entity Relationship Diagram
+
+```
+┌──────────┐       ┌──────────┐       ┌─────────────┐       ┌──────────┐
+│  USERS   │──1:N──│  ORDERS  │──1:N──│ ORDER_ITEMS │──N:1──│ PRODUCTS │
+│──────────│       │──────────│       │─────────────│       │──────────│
+│ id    PK │       │ id    PK │       │ id       PK │       │ id    PK │
+│ email    │       │ user_id FK│       │ order_id FK │       │ name     │
+│ name     │       │ status   │       │ product_id FK│       │ price    │
+│created_at│       │created_at│       │ quantity    │       └──────────┘
+└──────────┘       └──────────┘       └─────────────┘
+```
+
+## Tables
+
+### Table: {table_name}
+
+**Description**: {What this table stores and its role in the system.}
+
+#### Columns
+
+| Column | Type | Nullable | Default | Constraints | Description |
+|--------|------|----------|---------|-------------|-------------|
+| id | UUID | No | gen_random_uuid() | PRIMARY KEY | Unique identifier |
+| {column_name} | {type} | {Yes/No} | {default or —} | {UNIQUE, CHECK, etc.} | {description} |
+| {column_name} | {type} | {Yes/No} | {default or —} | {constraints} | {description} |
+| created_at | TIMESTAMPTZ | No | now() | — | Record creation time |
+| updated_at | TIMESTAMPTZ | No | now() | — | Last modification time |
+
+#### Indexes
+
+| Name | Columns | Type | Description |
+|------|---------|------|-------------|
+| {index_name} | {column(s)} | BTREE / GIN / GIST / HASH | {why this index exists — what query it optimizes} |
+| {index_name} | {column(s)} | UNIQUE | {enforces uniqueness on...} |
+
+#### Foreign Keys
+
+| Column | References | On Delete | On Update | Description |
+|--------|-----------|-----------|-----------|-------------|
+| {column} | {table.column} | CASCADE / SET NULL / RESTRICT | CASCADE | {description} |
+
+---
+
+### Table: {next_table_name}
+
+**Description**: {What this table stores.}
+
+#### Columns
+
+| Column | Type | Nullable | Default | Constraints | Description |
+|--------|------|----------|---------|-------------|-------------|
+| id | UUID | No | gen_random_uuid() | PRIMARY KEY | Unique identifier |
+
+#### Indexes
+
+| Name | Columns | Type | Description |
+|------|---------|------|-------------|
+
+#### Foreign Keys
+
+| Column | References | On Delete | On Update | Description |
+|--------|-----------|-----------|-----------|-------------|
+
+---
+
+## Relationships Summary
+
+| Relationship | Type | Description |
+|-------------|------|-------------|
+| {table_a} -> {table_b} | One-to-Many | {description} |
+| {table_c} -> {table_d} | Many-to-Many (via {junction}) | {description} |
+| {table_e} -> {table_f} | One-to-One | {description} |
+
+## Migration Notes
+
+- {Any special migration considerations}
+- {Data backfill requirements}
+- {Backward compatibility notes}

package/skills/plan-architecture/templates/system-design.md

@@ -0,0 +1,111 @@
+# System Design
+
+## 1. System Overview
+
+{One paragraph describing what this system does, who it serves, and its primary value proposition.}
+
+## 2. Component Diagram
+
+```
+┌────────────────┐     ┌─────────────┐
+│ Client App     │────>│ API Gateway │
+└────────────────┘     └──────┬──────┘
+                              │
+                    ┌─────────┼─────────┐
+                    v                   v
+             ┌────────────┐     ┌──────────┐
+             │ Auth Service│     │Core Service│
+             └────────────┘     └─────┬────┘
+                                      │
+                        ┌─────────┬───┴───┬──────────┐
+                        v         v       v          v
+                  ┌──────────┐ ┌─────┐ ┌─────────┐ ┌────────┐
+                  │ Database │ │Cache│ │Msg Queue│ │ Worker │
+                  └──────────┘ └─────┘ └─────────┘ └───┬────┘
+                                                       │
+                                                       v
+                                                 ┌──────────┐
+                                                 │ Database │
+                                                 └──────────┘
+```
+
+## 3. Component Responsibilities
+
+### {Component Name}
+- **Purpose**: {what this component does}
+- **Technology**: {language, framework, runtime}
+- **Owns**: {what data/domain this component is responsible for}
+- **Depends on**: {what other components it calls}
+- **Depended on by**: {what components call it}
+- **Scaling**: {how this component scales — horizontal, vertical, auto}
+
+### {Component Name}
+- **Purpose**: {what this component does}
+- **Technology**: {language, framework, runtime}
+- **Owns**: {what data/domain this component is responsible for}
+- **Depends on**: {what other components it calls}
+- **Depended on by**: {what components call it}
+- **Scaling**: {how this component scales}
+
+## 4. Data Flow
+
+### Primary Flow: {flow name, e.g., "User creates an order"}
+```
+Client          API             Service         Database
+  │               │               │               │
+  │──POST /resource──>│               │               │
+  │               │──validate + process──>│               │
+  │               │               │──INSERT──>│
+  │               │               │<──confirmation──│
+  │               │<──result──│               │
+  │<──201 Created──│               │               │
+```
+
+### Secondary Flow: {flow name}
+{Describe or diagram the flow.}
+
+## 5. API Boundaries
+
+| Boundary | Protocol | Auth | Rate Limit |
+|----------|----------|------|------------|
+| Client -> API | HTTPS/REST | JWT | 100 req/min |
+| API -> Service | gRPC / HTTP | Service token | None (internal) |
+| Service -> Database | TCP | Connection pool | N/A |
+| Service -> Cache | TCP | N/A | N/A |
+
+## 6. Infrastructure
+
+### Environments
+| Environment | Purpose | URL | Notes |
+|-------------|---------|-----|-------|
+| Local | Development | localhost:{port} | Docker Compose |
+| Staging | Pre-production testing | {url} | Mirrors production |
+| Production | Live users | {url} | Auto-scaled |
+
+### Infrastructure Components
+- **Compute**: {e.g., Kubernetes, ECS, Lambda, bare VM}
+- **Database**: {e.g., PostgreSQL on RDS, MongoDB Atlas}
+- **Cache**: {e.g., Redis on ElastiCache}
+- **Queue**: {e.g., SQS, RabbitMQ, Kafka}
+- **Storage**: {e.g., S3 for file uploads}
+- **CDN**: {e.g., CloudFront for static assets}
+- **Monitoring**: {e.g., Datadog, Prometheus + Grafana}
+- **Logging**: {e.g., CloudWatch, ELK stack}
+
+## 7. Scalability Considerations
+
+### Current Capacity
+- Expected concurrent users: {number}
+- Expected requests per second: {number}
+- Expected data volume: {size over time}
+
+### Scaling Strategy
+- **Horizontal**: {which components scale horizontally and how}
+- **Vertical**: {which components need vertical scaling}
+- **Caching**: {what is cached, invalidation strategy}
+- **Database**: {read replicas, sharding, partitioning plans}
+
+### Bottlenecks and Mitigations
+| Bottleneck | When It Hits | Mitigation |
+|-----------|-------------|------------|
+| {component} | {at what scale} | {what to do} |

package/skills/plan-brainstorm/SKILL.md

@@ -0,0 +1,433 @@
+---
+name: plan-brainstorm
+description: "Use when the user wants to explore approaches before coding — says 'brainstorm', 'compare options', 'figure out the approach', 'what's the best way to', 'kick around ideas', 'design discussion' — and the work is not prototype-driven (library extraction, internal tool, refactor). For prototype-shaped work, /feature and /greenfield use wireframe + prototype phases instead — skip this skill there."
+---
+
+# Plan Brainstorm
+
+Turn ideas into fully formed designs through collaborative dialogue. Explore approaches with the user, evaluate tradeoffs, and produce an approved design spec that feeds into architecture and task decomposition.
+
+**When this skill is the wrong fit:** v6's prototype-driven default flow (concept → wireframe → prototype → iterate → codify) uses the working prototype itself as design exploration. The `harden` skill at Phase 5 codifies the decisions the prototype implicitly made. This skill is the non-prototype fallback — invoke it only when prototype/wireframe phases were skipped for legitimate reasons (e.g., headless library work).
+
+**Announce at start:** "I'm using the plan-brainstorm skill to explore approaches for this feature."
+
+<HARD-GATE>
+When this skill is invoked: do NOT proceed to plan-architecture, plan-task-decompose, or any implementation skill until you have presented a design and the user has approved it. Once this skill is on the path, the gate applies. The gate does NOT apply in v6 prototype-driven flow because this skill is not on the path there.
+</HARD-GATE>
+
+---
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | Requirements doc (`.forge/work/{type}/{name}/requirements.md`) or user description. Codebase analysis (`.forge/work/{type}/{name}/codebase-analysis.md`) if existing project. |
+| **Produces** | `.forge/work/{type}/{name}/brainstorm-approved.md` |
+| **Feeds into** | `plan-architecture` |
+| **Updates manifest** | `artifacts.brainstorm` |
+
+---
+
+## Anti-Pattern: "This Is Too Simple To Need A Design"
+
+Every feature gets a brainstorm. Short designs are fine, but a design must exist and be approved.
+
+---
+
+## Checklist
+
+Complete these steps in order:
+
+1. **Review inputs** -- read requirements, codebase analysis, and decision log
+2. **Ask clarifying questions** -- one at a time, understand purpose, constraints, success criteria
+3. **Propose 2-3 approaches** -- with tradeoffs and your recommendation
+4. **Present design** -- in sections scaled to complexity, get approval after each section
+5. **Write design doc** -- save to `.forge/work/{type}/{name}/brainstorm-approved.md`
+6. **Spec review loop** -- dispatch spec-reviewer subagent (max 3 iterations)
+7. **User reviews written spec** -- ask user to review before proceeding
+8. **Update feature manifest** -- record approval
+9. **Transition to architecture** -- invoke plan-architecture skill
+
+---
+
+## Process
+
+### Step 1: Review Inputs
+
+Before asking any questions, gather context:
+
+**Read requirements document:**
+- Open `.forge/work/{type}/{name}/requirements.md` if it exists
+- Identify must-have vs should-have requirements
+- Note acceptance criteria that will constrain the design
+- Flag any open questions that should have been resolved in requirements
+
+**Read codebase analysis (if existing project):**
+- Open `.forge/work/{type}/{name}/codebase-analysis.md` if it exists
+- Note existing patterns that the design should follow
+- Identify constraints from the current architecture
+- Note flagged risks that the design should address
+
+**Check decision log:**
+- Read `aiwiki/decisions/` for existing architectural decisions
+- Identify patterns already established in prior features
+- Do NOT propose approaches that contradict existing decisions without explicitly acknowledging the deviation and justifying it
+
+**Assess scope:**
+Before asking detailed questions, evaluate scope. If the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately:
+
+> "This looks like it covers multiple independent subsystems. Rather than designing everything at once, I recommend we break it into sub-projects and brainstorm each one separately. Here's how I'd split it: [list]. Which should we start with?"
+
+Each sub-project gets its own brainstorm -> architecture -> tasks cycle.
+
+### Step 1.5: Codex Mode Check
+
+Now that inputs are reviewed, run the Codex consent flow from `protocols/codex.md`. The selected mode applies for the rest of this skill's invocation.
+
+- **Takeover:** Dispatch Codex with the inputs + skill methodology to propose approaches. Claude handles user-facing clarifying questions and critiques Codex's proposals.
+- **Verify** or **Skip / Codex unavailable:** Proceed with the steps below. Step 3.5 will dispatch Codex to critique Claude's proposed approaches (Verify only).
+
+### Step 2: Ask Clarifying Questions
+
+Rules:
+
+- **One question per message.** Never bundle multiple questions into one message.
+- **Multiple choice preferred.** When possible, present 3-5 options with descriptions. Always include "Other" as a choice.
+- **Open-ended is fine** when the question genuinely cannot be multiple choice (e.g., "Describe the user journey").
+- **Build on context.** Reference requirements, codebase analysis, and previous answers.
+- **Stop when confident.** Do not ask questions for completeness -- ask questions because the answer changes the design.
+
+Focus areas for questions:
+
+1. **Intent** -- What problem does this solve? Why now?
+2. **Users** -- Who benefits? How do they interact with it?
+3. **Constraints** -- Technical, business, time, compliance limitations?
+4. **Integration** -- How does this fit with existing systems?
+5. **Scale** -- Expected usage volume? Growth expectations?
+6. **Success criteria** -- How do we know this worked?
+
+### Step 3: Propose 2-3 Approaches
+
+After you have enough context, present approaches in a structured format:
+
+```markdown
+## Approach A: {Name} (Recommended)
+
+**Summary:** One paragraph describing the approach.
+
+**How it works:**
+1. {Step 1}
+2. {Step 2}
+3. {Step 3}
+
+**Pros:**
+- {Advantage 1}
+- {Advantage 2}
+
+**Cons:**
+- {Disadvantage 1}
+- {Disadvantage 2}
+
+**Best when:** {Conditions where this approach shines}
+
+---
+
+## Approach B: {Name}
+
+{Same structure}
+
+---
+
+## Approach C: {Name}
+
+{Same structure}
+
+---
+
+## Recommendation
+
+I recommend **Approach {X}** because {reasoning that references the specific requirements and constraints discussed}.
+```
+
+Rules for approaches:
+
+- **Minimum 2, maximum 3 approaches.** Two is fine when the decision is binary. Four is too many.
+- **Lead with your recommendation.** Explain why.
+- **Be honest about tradeoffs.** Do not present a straw man to make your preferred approach look better.
+- **Reference existing patterns.** If the codebase analysis found specific patterns, approaches should work with them, not against them.
+- **Check decision log.** If a similar decision was made before, reference it. Propose consistency unless there is a good reason to deviate.
+- **Include effort estimates.** Rough relative sizing (e.g., "Approach A: ~3 tasks, Approach B: ~7 tasks").
+
+### Step 3.5: Critic Review of Approaches
+
+Before presenting approaches to the user, dispatch the **critic** subagent (Opus) to review all proposed approaches for feasibility, gaps, and risks. Provide the critic with the requirements document, the codebase analysis (if available), and the generated approaches.
+
+Present the critic's verdict alongside the approaches to the user. If the critic identifies critical gaps, address them before presenting.
+
+**Codex Verify:** Check the mode recorded at Step 1.5. If **Verify** was selected, dispatch Codex alongside the critic to critique the proposed approaches for feasibility blind spots, missing constraints, and underestimated risks. If **Takeover** was selected, skip this step (Codex already proposed approaches). If **Skip**, do nothing. Do NOT re-run the consent flow.
+
+#### Codex Integration
+
+**Modes:** Verify or Takeover | **Protocol:** `protocols/codex.md`
+
+- **Verify:** Claude proposes approaches, Codex critiques feasibility.
+- **Takeover:** Codex proposes approaches, Claude reviews and critiques.
+
+**When:** Step 3.5 — after generating approaches, alongside the critic review.
+
+**Context to pass:**
+- Path to requirements document (`.forge/work/{type}/{name}/requirements.md`)
+- Path to codebase analysis (`.forge/work/{type}/{name}/codebase-analysis.md`)
+- Write proposed approaches to `.forge/work/{type}/{name}/brainstorm-approaches-draft.md` before invoking Codex (temp file — delete after critic review completes)
+
+**What Codex reviews:**
+- Feasibility blind spots in each approach
+- Missing constraints or requirements not addressed
+- Risks that the approaches underestimate
+
+**Prompt focus:** "Critique these proposed approaches. For each: what could go wrong that isn't acknowledged? What requirement is unaddressed? Which risks are underestimated?"
+
+**Presentation:** Present Claude critic + Codex critic findings together before the user selects an approach. Label each source.
+
+Wait for user to select an approach before proceeding.
+
+### Step 4: Present Design
+
+Once an approach is selected, present the detailed design in sections. Scale each section to its complexity -- a few sentences if straightforward, up to 200-300 words if nuanced.
+
+**After each section, ask if it looks right before continuing.** Do not dump the entire design at once.
+
+Sections to cover:
+
+**4a. Architecture Overview**
+- High-level component structure
+- How components communicate
+- Where this fits in the existing system (if applicable)
+
+**4b. Data Model**
+- Key entities and their relationships
+- Storage strategy (database tables, cache keys, file storage)
+- Data flow: where data enters, how it transforms, where it persists
+
+**4c. API Design**
+- Key endpoints or interfaces
+- Input/output shapes (high level -- exact contracts come in architecture skill)
+- Authentication and authorization approach
+
+**4d. User-Facing Behavior**
+- What the user sees and does
+- Key interaction flows
+- Error states and how they are communicated
+
+**4e. Error Handling Strategy**
+- How errors are detected, propagated, and reported
+- Retry strategies if applicable
+- Degradation behavior (what happens when a dependency fails)
+
+**4f. Testing Strategy**
+- What types of tests are needed
+- Key test scenarios
+- Any special testing infrastructure required
+
+**4g. Migration / Rollout Plan** (if modifying existing system)
+- How to deploy without breaking existing functionality
+- Rollback strategy
+- Data migration approach if needed
+
+Not every section applies to every feature. Skip sections that are not relevant, but do not skip sections because they seem simple -- briefly address them and move on.
+
+### Step 5: Write Design Doc
+
+After the user approves all sections, write the complete design to `.forge/work/{type}/{name}/brainstorm-approved.md`.
+
+The document MUST include:
+
+```markdown
+# Design: {Feature Name}
+
+**Date:** YYYY-MM-DD
+**Status:** Approved
+**Approach:** {Selected approach name}
+
+## Context
+{Why this feature exists, what problem it solves}
+
+## Requirements Summary
+{Link to requirements doc, key must-haves listed}
+
+## Selected Approach
+{The chosen approach with full rationale}
+
+## Alternatives Considered
+{Brief summary of rejected approaches and why}
+
+## Design
+
+### Architecture Overview
+{Component structure, communication patterns}
+
+### Data Model
+{Entities, relationships, storage}
+
+### API Design
+{Endpoints, interfaces, auth}
+
+### User-Facing Behavior
+{Interaction flows, UI behavior}
+
+### Error Handling
+{Error strategy}
+
+### Testing Strategy
+{Test types and key scenarios}
+
+### Migration / Rollout
+{Deployment strategy, rollback plan}
+
+## I/O Contract
+{What this design requires from other systems and what it provides}
+
+## Open Decisions
+{Any decisions deferred to architecture phase -- should be minimal}
+
+## Decision Log References
+{Links to relevant ADRs in aiwiki/decisions/}
+```
+
+### Step 6: Spec Review Loop
+
+After writing the spec document, dispatch a spec-reviewer subagent:
+
+1. **Dispatch spec-reviewer** with precisely crafted review context -- provide the path to the spec document and the requirements document. Never send your session history. This keeps the reviewer focused on the plan.
+2. **If issues found:** Fix the issues in the spec, then re-dispatch the reviewer.
+3. **If approved:** Proceed to user review.
+4. **Max 3 iterations.** If the review loop exceeds 3 iterations without convergence, surface the remaining issues to the user for guidance.
+
+The reviewer checks for:
+- Completeness against requirements (every must-have addressed)
+- Internal consistency (no contradictions within the design)
+- Feasibility (no hand-waving over hard problems)
+- Clarity (another developer could implement from this spec)
+
+### Step 7: User Reviews Written Spec
+
+After the spec review loop passes:
+
+> "Design spec written and saved to `.forge/work/{type}/{name}/brainstorm-approved.md`. Please review it and let me know if you want to make any changes before we move to architecture."
+
+Wait for the user's response. If they request changes, make them and re-run the spec review loop. Only proceed once the user explicitly approves.
+
+### Step 8: Update Feature Manifest
+
+After approval, update `.forge/work/{type}/{name}/manifest.yaml`:
+
+```yaml
+artifacts:
+  brainstorm:
+    path: brainstorm-approved.md
+    status: approved
+    approved_at: YYYY-MM-DD
+    approach: {selected approach name}
+    review_iterations: N
+```
+
+### Step 9: Transition to Architecture
+
+After the user approves the spec:
+
+> "Design approved. Next step: generating technical artifacts (API contracts, DB schemas, system diagrams). I'll use the plan-architecture skill."
+
+Invoke `plan-architecture`. Do NOT invoke any other skill. plan-architecture is the next step.
+
+---
+
+## Key Rules
+
+1. **NO implementation during brainstorming.** Design only. No code, no scaffolding, no file creation beyond the spec document.
+2. **No "too simple" exemption.** Every feature gets a brainstorm. The design can be short, but it must exist and be approved.
+3. **One question per message.** Do not overwhelm the user with multiple questions.
+4. **Multiple choice preferred.** Easier to answer than open-ended.
+5. **YAGNI ruthlessly.** If a capability is not in the requirements, do not design it. If the user suggests gold-plating, gently push back.
+6. **Check the decision log.** Before proposing a new pattern, check if a prior decision already covers it. Consistency matters more than novelty.
+7. **Incremental validation.** Present design in sections. Get approval per section. Do not present a 2000-word design and ask "does this look good?"
+8. **Explore alternatives before settling.** Always propose 2-3 approaches. Never jump to "the obvious solution" without showing why it is better than alternatives.
+9. **Reference codebase conventions.** If the codebase analysis found specific patterns, the design must work with them or explicitly justify deviation.
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Is Wrong | What To Do Instead |
+|---|---|---|
+| **Jumping to implementation** | Designs are cheap. Rework is expensive. | Present the design. Wait for approval. |
+| **Asking all questions at once** | Users give incomplete answers to question lists | One question per message. Build on answers. |
+| **Proposing only one approach** | No comparison means no informed decision | Always propose 2-3 with tradeoffs. |
+| **Ignoring existing patterns** | Fighting the codebase creates maintenance burden | Read codebase analysis. Follow conventions. |
+| **Skipping the review loop** | Unreviewed specs have gaps | Always dispatch spec-reviewer. |
+| **Hand-waving hard parts** | "We'll figure out auth later" becomes a crisis | Address every component, even briefly. |
+| **Over-designing simple features** | 10-page spec for a config change wastes time | Scale sections to complexity. Short is fine. |
+| **Contradicting prior decisions** | Inconsistency across features confuses everyone | Check decision log. Reference existing ADRs. |
+
+---
+
+## Design for Isolation and Clarity
+
+Break the system into units with one clear purpose, each communicating through well-defined interfaces. If a consumer can't be insulated from a unit's internals, the boundary needs work.
+
+---
+
+## Working in Existing Codebases
+
+- Explore the current structure before proposing changes. Follow existing patterns.
+- Where existing code has problems that affect the work (e.g., a file that has grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design.
+- Do not propose unrelated refactoring. Stay focused on what serves the current goal.
+- Reference specific files and patterns from the codebase analysis document.
+
+---
+
+## Process Flow
+
+```
+Review inputs (requirements + codebase analysis + decision log)
+    |
+    v
+Ask clarifying questions (one per message)
+    |
+    v
+Propose 2-3 approaches with tradeoffs
+    |
+    v
+User selects approach
+    |
+    v
+Present design in sections (approve each)
+    |
+    v
+  All sections approved?
+    |           |
+    no          yes
+    |           |
+    v           v
+  Revise    Write design doc
+              |
+              v
+         Spec review loop (max 3)
+              |
+              v
+         Review passed?
+            |         |
+            no        yes
+            |         |
+            v         v
+          Fix     User reviews spec
+                    |          |
+                    no         yes
+                    |          |
+                    v          v
+                  Revise    Update manifest
+                              |
+                              v
+                        Invoke plan-architecture
+```
+
+**The terminal state is invoking plan-architecture.** Do NOT invoke build-tdd, build-scaffold, or any other implementation skill. The ONLY skill you invoke after plan-brainstorm is plan-architecture.