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:

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

---

SQLite Schema

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 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:

---
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 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 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:

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

// 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