@cofoundr/init 1.5.0

package/content/commands/document.md

@@ -0,0 +1,155 @@
+---
+description: >
+  Generate or refresh living documentation derived from the code itself.
+  Targets: a module, a route, a feature folder, or "all". Produces docs in
+  `.cofoundr/docs/` (and updates module-level READMEs only if asked). Re-runnable
+  — every run reflects the current state of the code, not what it used to do.
+---
+
+# /cofoundr:document — Living Documentation
+
+You generate documentation from code. Documentation that reflects what the code **is**, not what someone wishes it would be. This command is re-runnable — every run regenerates the artifacts so they don't go stale.
+
+## Argument parsing
+
+- `/cofoundr:document` — auto-pick. If `.cofoundr/memory/codebase.md` exists, document the largest under-documented module. Otherwise, suggest `/cofoundr:onboard` first.
+- `/cofoundr:document module <path>` — document a specific module or directory.
+- `/cofoundr:document route <method> <path>` — document a single API route.
+- `/cofoundr:document feature <slug>` — refresh the feature doc in `docs/features/<slug>/`.
+- `/cofoundr:document data-model` — produce or refresh `.cofoundr/docs/data-model.md`.
+- `/cofoundr:document all` — full pass. Use sparingly; this is a long run.
+
+## Step 0 — Pre-flight
+
+- Refuse if `.cofoundr/memory/codebase.md` is older than the most recent commit by more than 14 days. Suggest `/cofoundr:onboard --refresh` first.
+- Refuse to write into `src/`, `app/`, `lib/`, etc. **Always** write into `.cofoundr/docs/<topic>.md` or `docs/...`. The code itself is read-only here.
+
+## Step 1 — Read
+
+For the chosen target:
+
+1. **Module / directory** — list every file, read the public exports, read every test file in or adjacent to the directory.
+2. **Route** — read the handler, all middleware in its chain, the request/response types, and any test that exercises it.
+3. **Data model** — read the schema (Prisma, Drizzle, Rails schema, migrations folder). Reconstruct the full set of tables, columns, indexes, foreign keys, and policies.
+4. **Feature** — read every file referenced in `docs/features/<slug>/feature.md` plus the tests.
+
+Always also read:
+
+- `.cofoundr/constitution.md` (or `docs/rules.md`) — to know what to surface as compliance posture.
+- `docs/tech.md` — to align terminology with the project spec.
+
+## Step 2 — Write
+
+Use the structure that fits the target.
+
+### Module / directory
+
+`.cofoundr/docs/modules/<module-slug>.md`
+
+```md
+# <Module name>
+
+## TL;DR
+<60 words: what the module does, who calls it>
+
+## Public surface
+<table of exported names → kind (function / class / type / route) → one-line description>
+
+## Internal shape
+<list of internal files, one-line each>
+
+## Dependencies
+<list of npm/pypi packages used + internal modules consumed>
+
+## Data touchpoints
+<which tables / collections / external APIs this module reads or writes>
+
+## Tests
+<list of test files; coverage summary if it exists>
+
+## Risks and gotchas
+<list, sourced from comments tagged TODO/FIXME/XXX, recent commit messages, and known constitution rules that touch this module>
+```
+
+### Route
+
+`.cofoundr/docs/routes/<method>-<slug>.md`
+
+```md
+# <METHOD> <path>
+
+## Purpose
+<one paragraph>
+
+## Auth
+<who can call it, how, source-of-truth file>
+
+## Request
+<schema + example>
+
+## Response
+<schema + example>
+
+## Errors
+<table: code | when it fires | how the client should react>
+
+## Side effects
+<DB writes, external API calls, jobs enqueued>
+
+## Tests
+<files that cover this route>
+```
+
+### Data model
+
+`.cofoundr/docs/data-model.md`
+
+```md
+# Data Model
+
+## ERD
+<mermaid `erDiagram` block, one entity per table, with foreign keys>
+
+## Tables
+### <table_name>
+- **Purpose:** <one sentence>
+- **Columns:** <table: name | type | constraints>
+- **Foreign keys:** <list>
+- **Indexes:** <list>
+- **RLS / authorization:** <quote the actual policy or "none — open">
+
+## Migrations
+<chronological list of migration files with one-line summary>
+```
+
+### Feature
+
+If `docs/features/<slug>/feature.md` exists, update its **Implementation Notes** and **Surfaces** sections only. Never overwrite Goals or Acceptance Criteria — those belong to `/cofoundr:new-feature`.
+
+## Step 3 — Provenance footer
+
+Every file you write must end with:
+
+```md
+---
+<sub>Generated by /cofoundr:document on <YYYY-MM-DD> from commit <git short SHA>. Re-run after code changes to refresh.</sub>
+```
+
+## Step 4 — Index
+
+After writing, update `.cofoundr/docs/INDEX.md` (create if missing) with one line per generated file:
+
+```
+- [<title>](<relative path>) — refreshed <YYYY-MM-DD>, commit <SHA>.
+```
+
+## Step 5 — Confirm
+
+Tell the founder what was generated and where, and which targets were skipped (and why). Suggest the next target.
+
+## What you must not do
+
+- Do not generate documentation for code you have not read. Skim is not enough.
+- Do not invent error codes, status codes, or schema fields. If you cannot find them, write `<!-- GAP -->`.
+- Do not modify any file under `src/`, `app/`, `lib/`, etc.
+- Do not duplicate a module's existing `README.md` under `.cofoundr/docs/`. If a module already documents itself, link to it and stop.

package/content/commands/implement.md

@@ -0,0 +1,108 @@
+---
+description: >
+  Execute the next unchecked task in the active phase or feature. Enforces the
+  constitution, runs the task's <verify> check, writes a Session Notes entry,
+  and stops cleanly at HALT conditions. The actual building command —
+  /cofoundr:tasks plans, /cofoundr:implement builds.
+---
+
+# /cofoundr:implement — Build the Next Task
+
+You execute one task at a time. Plan, verify, commit. You do not freelance — you do exactly the task you were given and nothing more.
+
+## Argument parsing
+
+- `/cofoundr:implement` — execute the next unchecked task in the active phase or feature.
+- `/cofoundr:implement T<N>` — execute a specific task.
+- `/cofoundr:implement phase <N>` — work through a phase, one task at a time, pausing for confirmation between tasks.
+- `/cofoundr:implement feature <slug>` — same, scoped to a feature.
+
+Default behavior: run **one** task, stop, ask. Never run multiple tasks without explicit confirmation.
+
+## Step 1 — Pre-flight
+
+Read in this order:
+
+1. `.cofoundr/constitution.md` (or `docs/rules.md`). Cache the Never list.
+2. `docs/tech.md` — stack and version pins.
+3. The active task's spec — find it in `docs/phases/<slug>/tasks.md` or `docs/features/<slug>/tasks.md`.
+4. The Boundary Map for the phase. The task may not consume an artifact that does not yet exist.
+5. `git status`. Working tree must be clean — if it is not, ask the founder whether to commit, stash, or abort.
+
+If any of these fail, **stop and report**. Do not start writing code with a dirty tree, a missing constitution, or a missing spec.
+
+## Step 2 — Announce
+
+Tell the founder, in plain language, exactly what you are about to do:
+
+```
+Task: T<N> — <task name>
+Files I will touch: <list>
+Verify check: <the <verify> line from tasks.md>
+Estimated change size: <small | medium | large>
+```
+
+If the change is **large**, stop and ask: *"This task touches more than 3 files. Want me to split it before I build, or proceed?"*
+
+If a Never rule applies, **stop**. Quote the rule and explain why the task as written would violate it. Do not build.
+
+## Step 3 — Build
+
+Build the task. Rules:
+
+- **One commit per task.** Format: `<phase or feature>: T<N> <imperative summary>`.
+- **No surprise edits.** Touch only the files named in the task. If you need to touch another file, stop and ask.
+- **Pin versions.** If the task adds a dependency, pin the exact major version.
+- **No `any` in TypeScript.** Constitution rule.
+- **Server-side validation.** Constitution rule.
+- **Test as you go.** If the project has a test setup, write or update the relevant test.
+
+If you hit a wall — three consecutive failed attempts at the same step, an unexpected dependency, a contradiction with another file — **HALT**. Write a note to `.cofoundr/memory/decisions.md`:
+
+```
+- <YYYY-MM-DD> HALT during T<N> (<task name>): <what happened, in one sentence>
+```
+
+## Step 4 — Verify
+
+Run the task's `<verify>` check. If it does not pass:
+
+1. Capture the failure verbatim.
+2. **Diagnose, do not patch.** A failing verify means either the task was wrong or the build is wrong. Identify which.
+3. If the task was wrong, surface the issue — do not silently rewrite the task.
+4. If the build is wrong, fix it. One more attempt only. If it fails again, HALT.
+
+## Step 5 — Update state
+
+After the verify check passes:
+
+1. Tick the task's checkbox in `tasks.md`.
+2. If the task was the last in the phase, tick the phase entry in `phases.md`.
+3. Append a Session Notes entry to the active feature doc:
+   ```
+   ## <YYYY-MM-DD HH:MM> — Session Notes
+   Done: T<N> <name>. <one-sentence diff summary>.
+   Next: <T<N+1> name, or "phase complete">.
+   Open: <blockers, if any>.
+   ```
+4. Run `/cofoundr:rules-check` against the new commit if the project has the command available. Surface any violations before claiming the task is done.
+
+## Step 6 — Commit and report
+
+Commit. Report:
+
+```
+T<N> done. <one-sentence summary>.
+Verify: passed.
+Next task: T<N+1> — <name>. Run /cofoundr:implement to start it.
+```
+
+Stop. Do not start the next task without explicit confirmation.
+
+## What you must not do
+
+- Do not skip the constitution read. Every implement run starts with it.
+- Do not run multiple tasks back-to-back unless the founder said "do the whole phase" or "auto-pilot until you hit a HALT". Even then, surface the boundary at every HALT condition.
+- Do not introduce dependencies, frameworks, or tools that are not in `docs/tech.md`. If the task implies one is needed, surface it via `/cofoundr:scope-guard` and let the founder decide.
+- Do not modify spec files (`product.md`, `prd.md`, `tech.md`, `rules.md`, `phases.md`, `agents.md`) during an implement run. Spec changes belong in their own command.
+- Do not use destructive commands (`rm -rf`, `DROP TABLE`, `--force`) without explicit user confirmation, even if the task technically asks for them.

package/content/commands/new-feature.md

@@ -0,0 +1,188 @@
+---
+description: >
+  Add a new feature to an existing project. Scope-checks against product.md
+  non-goals, runs a short 4-question planning conversation for the feature
+  only, and creates a living feature document in docs/features/. Before
+  writing any changes to the canonical spec files, it shows a diff and
+  asks for confirmation — so you always see what's about to change.
+---
+
+# New Feature — Scoped Addition
+
+Run this process when adding a feature to a project that already has spec files. Same persona as `/cofoundr:plan`: firm on detail, kind in tone, research-backed pushback only (verify with Context7 or WebSearch before correcting — never from memory).
+
+## Step 1 — Context Check
+
+1. Read the existing `product.md` if it exists — understand what the product is and what it is NOT.
+2. Read the existing `prd.md` if it exists — understand the current feature set and priorities.
+3. Read the existing `rules.md` if it exists — understand the behavioral constraints.
+4. Read `phases.md` if it exists — identify the current milestone and the last completed phase, so the new feature is inserted at the right position.
+
+If none of these files exist, suggest running `/cofoundr:new-project` first.
+
+## Step 2 — Feature Description
+
+Ask: "What feature are we adding? Describe what the user should be able to do."
+
+## Step 3 — Scope Check
+
+Check: does this feature fit within the existing product scope (product.md's "What This Is NOT" section)?
+
+- **If it conflicts with a non-goal:** Flag it. Say: "This conflicts with [non-goal from product.md]. This would be a pivot, not a feature addition. Do you want to update the product definition, or log this as a future idea in `ideas/FUTURE-IDEAS.md`?"
+- **If it fits:** Proceed to Step 4.
+
+## Step 4 — Feature Planning Conversation
+
+Ask only the questions that haven't already been answered, one at a time:
+
+1. What is the ONE thing this feature needs to do?
+2. Who uses this specific feature, and what breaks for them if it doesn't exist?
+3. What is this feature explicitly NOT doing?
+4. What does done look like — how will we verify it works?
+
+If an answer is vague, ask one follow-up. If an answer asserts something about a library, API, or service you're not sure is current, verify with Context7 or WebSearch before proceeding — and share what you found.
+
+## Step 5 — Create the Feature Document
+
+Create a file at `docs/features/[feature-slug].md` using the structure below. This is the living document for this feature — it must be updated throughout the build, not just at the start.
+
+The slug is the feature name in lowercase-kebab-case (e.g., "email-notifications", "csv-export").
+
+```markdown
+---
+description: >
+  Living document for [Feature Name]. Update this file as work progresses.
+---
+
+# Feature: [Feature Name]
+
+## TL;DR
+[≤30 words: what this feature does and who it's for]
+
+**Status:** `In Progress`
+**Milestone:** Milestone [N] — [Milestone Name]
+**Phase:** Phase [N.N] — [Phase Name]
+**Added:** [today's date]
+**Last updated:** [today's date]
+
+---
+
+## Acceptance Criteria
+[Observable behaviors a founder can verify by looking at the screen. Min 2.]
+
+- [ ] ...
+- [ ] ...
+
+## Dependencies
+[What must already exist. Reference the specific phase.]
+
+- ...
+
+## Scope Boundaries
+[What this feature explicitly does NOT do.]
+
+- Not ...
+
+---
+
+## Build Progress
+
+### Tasks
+- [ ] Task 1 — `[file/path]`
+- [ ] Task 2 — `[file/path]`
+- [ ] Task 3 — `[file/path]`
+
+### Blockers
+*None*
+
+---
+
+## Session Notes
+**[today's date] — Started**
+Done: Feature document created. Spec reviewed.
+Next: [first task to tackle]
+Decisions: [any decisions made during the planning conversation]
+Risks: [anything that could go wrong]
+```
+
+## Step 6 — Plan the Spec-File Changes
+
+Before writing any changes to the canonical spec files, decide what needs to change:
+
+1. **`prd.md`:** Add the feature at the appropriate priority level (P1 unless the founder explicitly promotes to P0).
+2. **`phases.md`:** Add a corresponding phase or decimal phase under the correct milestone, with tasks, file paths, `<verify>` blocks, a Boundary Map, and HALT conditions.
+3. **`tech.md`:** If the feature requires new schema, new endpoints, or new integrations, prepare those additions.
+4. **`rules.md`:** If the feature introduces new security or compliance considerations, prepare the new rule entries and a version bump in the YAML frontmatter.
+
+Do not write yet. Move to Step 7.
+
+## Step 7 — Show the Diff Before Writing
+
+The founder is about to have four of their canonical spec files modified. They need to see what's changing before it's written — silently editing four files is the fastest way to lose trust, especially for a non-technical user who won't spot a bad edit until a later build session breaks.
+
+Present a diff-style summary, file by file. Use this format:
+
+```
+── Proposed changes ────────────────────────────────
+
+📄 docs/prd.md
+   + New entry under "P1 Should Have":
+     [feature name] — [one-line summary]
+     Acceptance criteria: [N items]
+
+📄 docs/phases.md
+   + New phase [N.N] — [phase name], under Milestone [N]
+     Tasks: [count]
+     HALT conditions: [count]
+
+📄 docs/tech.md
+   + [or "no changes needed"]
+     [short description of additions, e.g. "New table `feature_foo`,
+     new endpoint POST /api/foo"]
+
+📄 docs/rules.md
+   + [or "no changes needed"]
+     Version: 1.0.0 → 1.0.1
+     New Always rule: [one-liner]
+     Amendment Log entry: "Added because [reason]"
+
+📄 docs/features/[slug].md
+   + NEW FILE (the living feature doc from Step 5)
+
+📄 docs/ACTIVE.md
+   + New @ import line: @docs/features/[slug].md
+
+📄 CLAUDE.md (project root)
+   [only if @docs/ACTIVE.md isn't already imported]
+   + New last line: @docs/ACTIVE.md
+
+────────────────────────────────────────────────────
+```
+
+Then ask:
+
+> Ready to apply these changes? Say 'yes' / 'apply' / 'go', or tell me what to adjust.
+
+Wait for a natural-language confirmation. Do not require a special token.
+
+## Step 8 — Apply the Changes
+
+Once confirmed:
+
+1. Write the new feature doc at `docs/features/[feature-slug].md` (Step 5 content).
+2. Apply the edits to `prd.md`, `phases.md`, `tech.md` (if needed), and `rules.md` (if needed — and bump version in the YAML frontmatter, add Amendment Log entry).
+3. Create or update `docs/ACTIVE.md` to append the `@` import for the new feature file. Do not remove existing entries.
+4. If `CLAUDE.md` in the project root does not already contain `@docs/ACTIVE.md`, add it as the last line. This ensures every future session automatically loads active feature context.
+5. Present a summary: what files were written, what was bumped, and confirm the feature is now registered. Ask if the founder wants to start building the first task, review the changes, or stop here.
+
+---
+
+## During the Build — Keeping the Feature Doc Current
+
+The feature document at `docs/features/[slug].md` must stay current throughout the build. The following updates are mandatory:
+
+- **After each completed task:** Check off the task checkbox and add the completion date.
+- **When a blocker is hit:** Add it to the Blockers section immediately.
+- **When a blocker is resolved:** Remove it from the Blockers section.
+- **At the end of every session:** Add a new Session Notes entry (newest at top) with: what was done, what's next, any decisions made, any risks identified.
+- **When the feature ships:** Set Status to `Complete`, add a final Session Notes entry, and remove the feature's `@` import line from `docs/ACTIVE.md`.