Codewalkers/docs/archive/initiatives.md

# Initiatives Module

Initiatives are the planning layer for larger features. They provide a Notion-like document hierarchy for capturing context, decisions, and requirements before work begins. Once approved, initiatives generate phased task plans that agents execute.

## Design Philosophy

### Why Initiatives?

Tasks are atomic work units—great for execution but too granular for planning. Initiatives bridge the gap:

- **Before approval**: A living document where user and Architect refine the vision
- **After approval**: A persistent knowledge base that tasks link back to
- **Forever**: Context for future work ("why did we build it this way?")

### Notion-Like Structure

Initiatives aren't flat documents. They're hierarchical pages:

```
Initiative: User Authentication
├── User Journeys
│   ├── Sign Up Flow
│   └── Password Reset Flow
├── Business Rules
│   └── Password Requirements
├── Technical Concept
│   ├── JWT Strategy
│   └── Session Management
└── Architectural Changes
    └── Auth Middleware
```

Each "page" is a record in SQLite with parent-child relationships. This enables:
- Structured queries: "Give me all subpages of initiative X"
- Inventory views: "List all technical concepts across initiatives"
- Cross-references: Link between pages

---

## Data Model

### Initiative Entity

| Field | Type | Description |
|-------|------|-------------|
| `id` | TEXT | Primary key (e.g., `init-a1b2c3`) |
| `project_id` | TEXT | Scopes to a project (most initiatives are single-project) |
| `title` | TEXT | Initiative name |
| `status` | TEXT | `draft`, `review`, `approved`, `in_progress`, `completed`, `rejected` |
| `created_by` | TEXT | User who created it |
| `created_at` | INTEGER | Unix timestamp |
| `updated_at` | INTEGER | Unix timestamp |
| `approved_at` | INTEGER | When approved (null if not approved) |
| `approved_by` | TEXT | Who approved it |

### Initiative Page Entity

| Field | Type | Description |
|-------|------|-------------|
| `id` | TEXT | Primary key (e.g., `page-x1y2z3`) |
| `initiative_id` | TEXT | Parent initiative |
| `parent_page_id` | TEXT | Parent page (null for root-level pages) |
| `type` | TEXT | `user_journey`, `business_rule`, `technical_concept`, `architectural_change`, `note`, `custom` |
| `title` | TEXT | Page title |
| `content` | TEXT | Markdown content |
| `sort_order` | INTEGER | Display order among siblings |
| `created_at` | INTEGER | Unix timestamp |
| `updated_at` | INTEGER | Unix timestamp |

### Initiative Phase Entity

Phases group tasks for staged execution and rolling approval.

| Field | Type | Description |
|-------|------|-------------|
| `id` | TEXT | Primary key (e.g., `phase-p1q2r3`) |
| `initiative_id` | TEXT | Parent initiative |
| `number` | INTEGER | Phase number (1, 2, 3...) |
| `name` | TEXT | Phase name |
| `description` | TEXT | What this phase delivers |
| `status` | TEXT | `draft`, `pending_approval`, `approved`, `in_progress`, `completed` |
| `approved_at` | INTEGER | When approved |
| `approved_by` | TEXT | Who approved |
| `created_at` | INTEGER | Unix timestamp |

### Task Link

Tasks reference their initiative and phase:

```sql
-- In tasks table (see docs/tasks.md)
initiative_id TEXT REFERENCES initiatives(id),
phase_id TEXT REFERENCES initiative_phases(id),
```

---

## SQLite Schema

```sql
CREATE TABLE initiatives (
  id TEXT PRIMARY KEY,
  project_id TEXT,
  title TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'draft'
    CHECK (status IN ('draft', 'review', 'approved', 'in_progress', 'completed', 'rejected')),
  created_by TEXT,
  created_at INTEGER NOT NULL DEFAULT (unixepoch()),
  updated_at INTEGER NOT NULL DEFAULT (unixepoch()),
  approved_at INTEGER,
  approved_by TEXT
);

CREATE TABLE initiative_pages (
  id TEXT PRIMARY KEY,
  initiative_id TEXT NOT NULL REFERENCES initiatives(id) ON DELETE CASCADE,
  parent_page_id TEXT REFERENCES initiative_pages(id) ON DELETE CASCADE,
  type TEXT NOT NULL DEFAULT 'note'
    CHECK (type IN ('user_journey', 'business_rule', 'technical_concept', 'architectural_change', 'note', 'custom')),
  title TEXT NOT NULL,
  content TEXT,
  sort_order INTEGER NOT NULL DEFAULT 0,
  created_at INTEGER NOT NULL DEFAULT (unixepoch()),
  updated_at INTEGER NOT NULL DEFAULT (unixepoch())
);

CREATE TABLE initiative_phases (
  id TEXT PRIMARY KEY,
  initiative_id TEXT NOT NULL REFERENCES initiatives(id) ON DELETE CASCADE,
  number INTEGER NOT NULL,
  name TEXT NOT NULL,
  description TEXT,
  status TEXT NOT NULL DEFAULT 'draft'
    CHECK (status IN ('draft', 'pending_approval', 'approved', 'in_progress', 'completed')),
  approved_at INTEGER,
  approved_by TEXT,
  created_at INTEGER NOT NULL DEFAULT (unixepoch()),
  UNIQUE(initiative_id, number)
);

CREATE INDEX idx_initiatives_project ON initiatives(project_id);
CREATE INDEX idx_initiatives_status ON initiatives(status);
CREATE INDEX idx_pages_initiative ON initiative_pages(initiative_id);
CREATE INDEX idx_pages_parent ON initiative_pages(parent_page_id);
CREATE INDEX idx_pages_type ON initiative_pages(type);
CREATE INDEX idx_phases_initiative ON initiative_phases(initiative_id);
CREATE INDEX idx_phases_status ON initiative_phases(status);

-- Useful views
CREATE VIEW initiative_page_tree AS
WITH RECURSIVE tree AS (
  SELECT id, initiative_id, parent_page_id, title, type, 0 as depth,
         title as path
  FROM initiative_pages WHERE parent_page_id IS NULL
  UNION ALL
  SELECT p.id, p.initiative_id, p.parent_page_id, p.title, p.type, t.depth + 1,
         t.path || ' > ' || p.title
  FROM initiative_pages p
  JOIN tree t ON p.parent_page_id = t.id
)
SELECT * FROM tree ORDER BY path;
```

---

## Status Workflow

### Initiative Status

```
  [draft] ──submit──▶ [review] ──approve──▶ [approved]
     │                   │                      │
     │                   │ reject               │ start work
     │                   ▼                      ▼
     │              [rejected]            [in_progress]
     │                                          │
     │                                          │ all phases done
     └──────────────────────────────────────────▶ [completed]
```

| Status | Meaning |
|--------|---------|
| `draft` | User/Architect still refining |
| `review` | Ready for approval decision |
| `approved` | Work plan created, awaiting execution |
| `in_progress` | At least one phase executing |
| `completed` | All phases completed |
| `rejected` | Won't implement |

### Phase Status

```
  [draft] ──finalize──▶ [pending_approval] ──approve──▶ [approved]
                                                            │
                                                            │ claim tasks
                                                            ▼
                                                       [in_progress]
                                                            │
                                                            │ all tasks closed
                                                            ▼
                                                       [completed]
```

**Rolling approval pattern:**
1. Architect creates work plan with multiple phases
2. User approves Phase 1 → agents start executing
3. While Phase 1 executes, user reviews Phase 2
4. Phase 2 approved → agents can start when ready
5. Continue until all phases approved/completed

This prevents blocking: agents don't wait for all phases to be approved upfront.

---

## Workflow

### 1. Draft Initiative

User creates initiative with basic vision:

```
cw initiative create "User Authentication"
```

System creates initiative in `draft` status with empty page structure.

### 2. Architect Iteration (Questioning)

Architect agent engages in structured questioning to capture requirements:

**Question Categories:**

| Category | Example Questions |
|----------|-------------------|
| **Visual Features** | Layout approach? Density? Interactions? Empty states? |
| **APIs/CLIs** | Response format? Flags? Error handling? Verbosity? |
| **Data/Content** | Structure? Validation rules? Edge cases? |
| **Architecture** | Patterns to follow? What to avoid? Reference code? |

Each answer populates initiative pages. Architect may:
- Create user journey pages
- Document business rules
- Draft technical concepts
- Flag architectural impacts

See [agents/architect.md](agents/architect.md) for the full Architect agent prompt.

### 3. Discussion Phase (Per Phase)

Before planning each phase, the Architect captures implementation decisions through focused discussion. This happens BEFORE any planning work.

```
cw phase discuss <phase-id>
```

Creates `{phase}-CONTEXT.md` with locked decisions:

```yaml
---
phase: 1
discussed_at: 2024-01-15
---

# Phase 1 Context: User Authentication

## Decisions

### Authentication Method
**Decision:** Email/password with optional OAuth
**Reason:** MVP needs simple auth, OAuth for convenience
**Locked:** true

### Token Storage
**Decision:** httpOnly cookies
**Reason:** XSS protection
**Alternatives Rejected:**
- localStorage: XSS vulnerable
```

These decisions guide all subsequent planning and execution. Workers reference CONTEXT.md for implementation direction.

### 4. Research Phase (Optional)

For phases with unknowns, run discovery before planning:

| Level | When | Time | Scope |
|-------|------|------|-------|
| L0 | Pure internal work | Skip | None |
| L1 | Quick verification | 2-5 min | Confirm assumptions |
| L2 | Standard research | 15-30 min | Explore patterns |
| L3 | Deep dive | 1+ hour | Novel domain |

```
cw phase research <phase-id> --level 2
```

Creates `{phase}-RESEARCH.md` with findings that inform planning.

### 5. Submit for Review

When Architect and user are satisfied:

```
cw initiative submit <id>
```

Status changes to `review`. Triggers notification for approval.

### 4. Approve Initiative

Human reviews the complete initiative:

```
cw initiative approve <id>
```

Status changes to `approved`. Now work plan can be created.

### 5. Create Work Plan

Architect (or user) breaks initiative into phases:

```
cw initiative plan <id>
```

This creates:
- `initiative_phases` records
- Tasks linked to each phase via `initiative_id` + `phase_id`

Tasks are created in `open` status but won't be "ready" until their phase is approved.

### 6. Approve Phases (Rolling)

User reviews and approves phases one at a time:

```
cw phase approve <phase-id>
```

Approved phases make their tasks "ready" for agents. User can approve Phase 1, let agents work, then approve Phase 2 later.

### 7. Execute

Workers pull tasks via `cw task ready`. Tasks include:
- Link to initiative for context
- Link to phase for grouping
- All normal task fields (dependencies, priority, etc.)

### 8. Verify Phase

After all tasks in a phase complete, the Verifier agent runs goal-backward verification:

```
cw phase verify <phase-id>
```

Verification checks:
1. **Observable truths** — What users can observe when goal is achieved
2. **Required artifacts** — Files that must exist (not stubs)
3. **Required wiring** — Connections that must work
4. **Anti-patterns** — TODOs, placeholders, empty returns

Creates `{phase}-VERIFICATION.md` with results. If gaps found, creates remediation tasks.

See [verification.md](verification.md) for detailed verification patterns.

### 9. User Acceptance Testing

After technical verification passes, run UAT:

```
cw phase uat <phase-id>
```

Walks user through testable deliverables:
- "Can you log in with email and password?"
- "Does the dashboard show your projects?"

Creates `{phase}-UAT.md` with results. If issues found, creates targeted fix plans.

### 10. Complete

When all tasks in all phases are closed AND verification passes:
- Each phase auto-transitions to `completed`
- Initiative auto-transitions to `completed`
- Domain layer updated to reflect new state

---

## Phase Artifacts

Each phase produces artifacts during execution:

| Artifact | Created By | Purpose |
|----------|------------|---------|
| `{phase}-CONTEXT.md` | Architect (Discussion) | Locked implementation decisions |
| `{phase}-RESEARCH.md` | Architect (Research) | Domain knowledge findings |
| `{phase}-{N}-PLAN.md` | Architect (Planning) | Executable task plans |
| `{phase}-{N}-SUMMARY.md` | Worker (Execution) | What actually happened |
| `{phase}-VERIFICATION.md` | Verifier | Goal-backward verification |
| `{phase}-UAT.md` | Verifier + User | User acceptance testing |

See [execution-artifacts.md](execution-artifacts.md) for artifact specifications.

---

## CLI Reference

### Initiative Commands

| Command | Description |
|---------|-------------|
| `cw initiative create <title>` | Create draft initiative |
| `cw initiative list [--status STATUS]` | List initiatives |
| `cw initiative show <id>` | Show initiative with page tree |
| `cw initiative submit <id>` | Submit for review |
| `cw initiative approve <id>` | Approve initiative |
| `cw initiative reject <id> --reason "..."` | Reject initiative |
| `cw initiative plan <id>` | Generate phased work plan |

### Page Commands

| Command | Description |
|---------|-------------|
| `cw page create <initiative-id> <title> --type TYPE` | Create page |
| `cw page create <initiative-id> <title> --parent <page-id>` | Create subpage |
| `cw page show <id>` | Show page content |
| `cw page edit <id>` | Edit page (opens editor) |
| `cw page list <initiative-id> [--type TYPE]` | List pages |
| `cw page tree <initiative-id>` | Show page hierarchy |

### Phase Commands

| Command | Description |
|---------|-------------|
| `cw phase list <initiative-id>` | List phases |
| `cw phase show <id>` | Show phase with tasks |
| `cw phase discuss <id>` | Capture implementation decisions (creates CONTEXT.md) |
| `cw phase research <id> [--level N]` | Run discovery (L0-L3, creates RESEARCH.md) |
| `cw phase approve <id>` | Approve phase for execution |
| `cw phase verify <id>` | Run goal-backward verification |
| `cw phase uat <id>` | Run user acceptance testing |
| `cw phase status <id>` | Check phase progress |

---

## Integration Points

### With Tasks Module

Tasks gain two new fields:
- `initiative_id`: Links task to initiative (for context)
- `phase_id`: Links task to phase (for grouping/approval)

The `ready_tasks` view should consider phase approval:

```sql
CREATE VIEW ready_tasks AS
SELECT t.* FROM tasks t
LEFT JOIN initiative_phases p ON t.phase_id = p.id
WHERE t.status = 'open'
  AND (t.phase_id IS NULL OR p.status IN ('approved', 'in_progress'))
  AND NOT EXISTS (
    SELECT 1 FROM task_dependencies d
    JOIN tasks dep ON d.depends_on = dep.id
    WHERE d.task_id = t.id
      AND d.type = 'blocks'
      AND dep.status != 'closed'
  )
ORDER BY t.priority ASC, t.created_at ASC;
```

### With Domain Layer

When initiative completes, its pages can feed into domain documentation:
- Business rules → Domain business rules
- Technical concepts → Architecture docs
- New aggregates → Domain model updates

### With Orchestrator

Orchestrator can:
- Trigger Architect agents for initiative iteration
- Monitor phase completion and auto-advance initiative status
- Coordinate approval notifications

### tRPC Procedures

```typescript
// Suggested tRPC router shape
initiative.create(input)           // → Initiative
initiative.list(filters)           // → Initiative[]
initiative.get(id)                 // → Initiative with pages
initiative.submit(id)              // → Initiative
initiative.approve(id)             // → Initiative
initiative.reject(id, reason)      // → Initiative
initiative.plan(id)                // → Phase[]

page.create(input)                 // → Page
page.get(id)                       // → Page
page.update(id, content)           // → Page
page.list(initiativeId, filters)   // → Page[]
page.tree(initiativeId)            // → PageTree

phase.list(initiativeId)           // → Phase[]
phase.get(id)                      // → Phase with tasks
phase.approve(id)                  // → Phase
phase.status(id)                   // → PhaseStatus
```

---

## Future Considerations

- **Templates**: Pre-built page structures for common initiative types
- **Cross-project initiatives**: Single initiative spanning multiple projects
- **Versioning**: Track changes to initiative pages over time
- **Approval workflows**: Multi-step approval with different approvers
- **Auto-planning**: LLM generates work plan from initiative content