omniconductor 0.3.0

package/core/anti-patterns/no-sub-agent-dispatch.md

@@ -0,0 +1,89 @@
+---
+anti_pattern_id: no-sub-agent-dispatch
+name: "No sub-agent dispatch — large work runs in main thread"
+type: anti-pattern
+severity: MEDIUM
+hit_rate_impact: "indirect: main-thread context bloat, output-token spike"
+detection_method:
+  - measure-tokens (sub-agent dispatches per session vs total tool calls)
+  - session JSONL size > 100MB on a non-trivial project
+applies_to: ["claude-code", "tools-with-native-sub-agent"]
+linked_rules:
+  - meta-discipline (5.3 sub-agent dispatch discipline, 7 flat-with-leader)
+---
+
+# Anti-Pattern 04 — No sub-agent dispatch
+
+## 1. What it is
+
+The orchestrator handles every task — multi-file refactors, large file generations, verbose test runs, repository searches — directly in the main thread, never dispatching to a role agent. All output, intermediate reasoning, and tool results accumulate in the leader's context.
+
+```
+# WRONG — 30 Reads + 12 Edits + 8 Bash test runs in main thread
+Main thread: "Let me audit all 24 page components for the redesign..."
+  Read page-1.tsx (full)
+  Read page-2.tsx (full)
+  ... (22 more)
+  Edit page-1.tsx
+  ... (23 more)
+  Bash npm test (verbose output)
+  Bash npm run build (verbose output)
+```
+
+By the end of the task the main-thread context holds the full text of 24 files plus build/test output — easily 100K+ tokens that linger for the rest of the session.
+
+## 2. Why it kills cache
+
+Sub-agent isolation is the cleanest known mechanism for context hygiene on tools that support it:
+
+- The dispatched role gets a fresh context, does the work, and returns a *summary* (typically 0.5-2K tokens).
+- The main thread accumulates only the summary, not the verbose intermediate state.
+- The cacheable prefix in the main thread stays small.
+
+Without dispatch:
+- Verbose test/build output (often 5-15K tokens) lives in main-thread history forever.
+- 24-file refactor leaves 24 file bodies in main-thread cache-read on every subsequent turn.
+- Cache-write per turn climbs as the conversation continues — cache hit rate stays high but the *absolute size* of cached content compounds.
+
+**Reference data** (Conductor P1.5 baseline): the two largest sessions (219MB + 187MB) both contained heavy in-thread work; smaller sessions with active dispatch use stayed under 70MB. Avg dispatches/session = 104.6. The recommended P2 target is -25% dispatch *frequency* (batch related work) but the *anti-pattern* of zero dispatch is far more costly than over-dispatch.
+
+## 3. Detection
+
+**Quantitative**:
+- Sub-agent dispatches / session = 0 on multi-feature work → red flag
+- Total tool calls / dispatches ratio > 200 → main-thread-heavy
+
+```bash
+# Reference command via measure-tokens.sh:
+bash tools/measure-tokens.sh --latest | grep -E 'dispatches|tool calls'
+```
+
+**Symptom**: session JSONL grows past 100MB; latency per turn climbs noticeably as the session ages.
+
+## 4. Fix / Alternative
+
+**Per `meta-discipline.md` §7 (flat-with-leader topology)**: orchestrator dispatches role agents. Roles never dispatch each other.
+
+Rules of thumb (when to dispatch):
+- Multi-file refactor (3+ files cross-cutting) → builder role
+- Verbose test/build runs → helper role with `output_format=summary`
+- Repository-wide search across an unfamiliar codebase → explorer role
+- Long-form documentation generation → scribe role
+- Anything expected to take > 2 min wall clock → background dispatch
+
+Dispatch brief budget: ≤ 2K tokens (per `meta-discipline.md` §5.3). Reference files by path, do NOT paste content.
+
+**Single-Agent Mode fallback**: tools that lack native sub-agents (Cursor, Copilot, Gemini, Codex, Windsurf) cannot use this fix. Conductor's `core/universal-rules/meta-discipline.md` §6.6 records this honestly. On those tools, mitigate with:
+- Aggressive auto-compact at ~70% context
+- Aggressive Grep-before-Read discipline
+- Output-redirect to file (run verbose tools with `> /tmp/log` and tail-Read only the last N lines)
+
+## 5. Severity rating
+
+**MEDIUM** — significant but tool-conditional. On Claude Code with native sub-agents, dispatch hygiene is the difference between a 65MB and a 220MB session JSONL. On tools without sub-agents, the rule degrades to compaction discipline.
+
+| Pattern | Main-thread context after 50 turns | Cost |
+|---|---|---|
+| All work in main thread | 100-200K tokens accumulated | high — every subsequent turn re-reads all of it |
+| Dispatch verbose work to roles | 10-20K tokens (summaries only) | low — main thread stays lean |
+| Dispatch + structured-summary return | 5-10K tokens | optimal |

package/core/anti-patterns/single-monolithic-rule-file.md

@@ -0,0 +1,99 @@
+---
+anti_pattern_id: single-monolithic-rule-file
+name: "Monolithic rule file — every rule in one auto-loaded document"
+type: anti-pattern
+severity: HIGH
+hit_rate_impact: "direct cache-write bloat; -20% effective hit benefit"
+detection_method:
+  - measure CLAUDE.md (or equivalent) line count — > 500 lines is suspect
+  - check for `paths:` / `globs:` / `applyTo:` frontmatter usage
+applies_to: ["all-tools"]
+linked_rules:
+  - meta-discipline (5.6 touched-file rule scoping)
+---
+
+# Anti-Pattern 03 — Single monolithic rule file
+
+## 1. What it is
+
+The project loads a single oversized rule file at session start — coding conventions, branch strategy, deployment notes, troubleshooting matrix, document map, full feature specs, all bundled in one document — instead of splitting into path-scoped bundles that load only when relevant files are touched.
+
+```markdown
+# WRONG — 1,800-line CLAUDE.md auto-loaded every session
+# Includes:
+#  - Workflow rules (relevant always)
+#  - Payment-provider webhook setup (relevant only when touching billing/)
+#  - Email templates (relevant only when touching email/)
+#  - Database migration log (relevant only when touching db/)
+#  - Bank-aggregator integration notes (relevant only when touching that area/)
+#  - Post-mortems from 6 months ago
+```
+
+Every turn carries the entire payload — including 1,400 lines that have nothing to do with the current task.
+
+## 2. Why it kills cache
+
+The file IS cacheable, so cache hit rate stays high. The damage is on a different axis: **cache-write inflation**.
+
+- Every session start writes the full prefix. Cache-write costs 1.25× input.
+- If the prefix is 25K tokens (mostly irrelevant), every new session pays 31K-token cache-write before any work begins.
+- The per-turn cache-read cost stays 0.1×, but the absolute number of read tokens scales with prefix size, so total cost still climbs linearly with prefix bloat.
+
+Conductor's P1.5 baseline shows avg cache-write per session = 27.4M tokens. The P2 target is -30% (to ~19M) — most of that reduction comes from splitting the monolithic file.
+
+## 3. Detection
+
+```bash
+# Find oversized rule files
+wc -l CLAUDE.md AGENT.md GEMINI.md .codex/codex.md 2>/dev/null | \
+  awk '$1 > 500 { print }'
+```
+
+**Code-level signal**: grep for `paths:` / `globs:` / `applyTo:` frontmatter inside rule files. Zero matches across the rules dir = monolithic anti-pattern.
+
+```bash
+grep -lE '^paths:|^globs:|^applyTo:' .claude/rules/*.md .cursor/rules/*.mdc 2>/dev/null | wc -l
+```
+
+**Session-level signal**: same uncached input + cache-write delta across a session of unrelated tasks (e.g., billing work and i18n work both pull the whole rule body).
+
+## 4. Fix / Alternative
+
+**Split by domain + scope by path** (per `meta-discipline.md` §5.6).
+
+The reference project keeps a thin top-level pointer file and 5-7 path-scoped rule files:
+
+```
+.claude/rules/
+├── workflow.md            (always loaded)
+├── spec-as-you-go.md      (always loaded)
+├── quality-gates.md       (always loaded)
+├── operations.md          (always loaded)
+├── meta-discipline.md     (always loaded)
+├── coding-conventions.md  (paths: apps/**/*.{ts,tsx})
+├── branch-strategy.md     (paths: .git*, ci/**)
+├── i18n.md                (paths: **/i18n/**, **/translations.ts)
+└── billing.md             (paths: **/stripe/**, **/billing/**)
+```
+
+Five always-loaded universal bundles ≈ 6K tokens (Conductor v0.2 reference figure). Path-scoped bundles only contribute when the touched-file glob matches.
+
+**Tool-specific frontmatter**:
+- Claude Code: `paths:` (matches Read/Edit/Write target)
+- Cursor: `globs:` in `.mdc`
+- Copilot: `applyTo:` in `.instructions.md`
+- Gemini / Codex: no native scoping → keep per-domain files small and link them by reference inside the main rule doc.
+
+**The "5-bundle floor"**: per Conductor `core/universal-rules/README.md`, the minimum auto-load is 5 universal-rule files totaling ~6K tokens. Anything beyond that should be path-scoped or recipe-installed (opt-in).
+
+## 5. Severity rating
+
+**HIGH** — directly multiplies every other cost. A 30K monolithic prefix turns every per-turn cache-read into 3K tokens billed (vs 600 for a 6K floor).
+
+| Rule strategy | Auto-load size | Per-100-turn cache-read |
+|---|---|---|
+| Monolithic single file | 25-30K | 250-300K tokens |
+| 5-bundle floor + path-scoped | 6K | 60K tokens |
+| Recipe opt-in only when touched | varies | adds 1-3K per matching turn |
+
+The 5-bundle + scoped recipe strategy delivers ~80% reduction in steady-state cache-read cost.

package/core/anti-patterns/skill-eager-load.md

@@ -0,0 +1,83 @@
+---
+anti_pattern_id: skill-eager-load
+name: "Skill / MCP eager-load — every helper injected at session start"
+type: anti-pattern
+severity: MEDIUM
+hit_rate_impact: "+ context bloat (200-600 tokens per skill, compounds)"
+detection_method:
+  - count auto-loaded skills / MCP servers at session start
+  - measure-tokens cache-write delta when skills are added
+applies_to: ["claude-code", "any-tool-with-skill-or-MCP-system"]
+linked_rules:
+  - meta-discipline (5.2 hidden injection awareness, 5.5 tool description compression)
+---
+
+# Anti-Pattern 07 — Skill / MCP eager-load
+
+## 1. What it is
+
+Every available skill or MCP server is registered to load eagerly at session start, regardless of whether the current task triggers it. Skill descriptions, tool schemas, and (worst case) full skill bodies enter the cacheable prefix.
+
+```yaml
+# WRONG — 30+ skills auto-loaded with full bodies
+skills:
+  - frontend-design        # 2K tokens, used in 5% of tasks
+  - email-template         # 1.5K tokens, used in 2% of tasks
+  - payment-webhook        # 2K tokens, used in 1% of tasks
+  - playwright-debugging   # 3K tokens, used in 10% of tasks
+  - ... (26 more)
+```
+
+In the originating project, certain Read paths trigger automatic skill injection:
+- `<web-app>/app/**` Read → `next-cache-components` + `next-forge` + `nextjs` (~600 tokens hidden cost per Read)
+- `src/components/**/*.tsx` Write → `react-best-practices` (~200 tokens)
+
+If the orchestrator does 50 Reads under those paths in a session, that is 30K tokens of hidden skill injection — none of which the current task may need.
+
+## 2. Why it kills cache
+
+Two failure modes:
+
+- **Prefix bloat**: lazy-loaded skill *descriptions* are usually small (~50 tokens each), but eager-loaded skill *bodies* are 1-3K each. 30 eager-loaded skills = 30-90K tokens of always-cached prefix.
+- **Hidden multiplier on Reads**: path-triggered skill injection happens *per Read*, not once per session. The hidden cost compounds with Anti-Pattern 02 (large-file Read).
+
+Per `meta-discipline.md` §5.2: "Some tools auto-inject skill / library docs when certain file paths are touched. These injections add hidden tokens (often 200-600 per Read)."
+
+Reference numbers (originating workspace's `token-economy.md`):
+- `<web-app>/app/**` Read: ~600 tokens auto-inject
+- `src/components/**/*.tsx` Write: ~200 tokens auto-inject
+
+In a 50-Read session those modifiers alone account for 10-30K tokens of cache-write churn that has no relationship to the user's task.
+
+## 3. Detection
+
+**Skill registry inspection**: at session start, count active skills with full body loaded vs description-only.
+
+**Session JSONL signal**: search for skill body content appearing repeatedly in tool-call results.
+
+**Symptom**: large uncached input + cache-write on the very first turn (before any user message has been processed) → eager-load weight.
+
+## 4. Fix / Alternative
+
+**Three layers of mitigation**:
+
+1. **Description-only skill loading** (per `meta-discipline.md` §5.5): the registry exposes skill names + 1-line descriptions. The skill body loads only when the skill is invoked. On Claude Code, the `Skill` tool already implements this pattern — abuse comes from explicit eager-load configuration.
+
+2. **Path-scoped auto-injection** (per `meta-discipline.md` §5.6): when a tool offers path-triggered skills, ensure the path glob is *narrow*. The reference project pays for `<web-app>/app/**` triggering 3 skills because that glob is broad. Narrowing to `<web-app>/app/api/**/route.ts` (Next.js route handlers only) reduces trigger frequency by ~80%.
+
+3. **MCP gateway / lazy-load proxy**: when many MCP servers are registered, route them through a lazy-loading proxy so only the tool *names* enter the prefix, with full schemas fetched on first use. Reference: `meta-discipline.md` §5.5.
+
+**Conductor's deferred-tool pattern**: this session uses `ToolSearch` to fetch tool schemas only when needed. That is the canonical example — tool names are visible in system reminders, but invoking a tool requires fetching its schema first. The same principle generalizes to skills.
+
+**Cache-position fix**: even when a skill *must* be loaded, position it inside the cacheable prefix (above the cache_control boundary) so subsequent Reads under that path benefit from cache-read pricing (0.1×) rather than fresh injection cost. See `docs/PROMPT-CACHING-GUIDE.md`.
+
+## 5. Severity rating
+
+**MEDIUM** — magnitude depends entirely on how many skills are eager-loaded and how broad the path triggers are. A project with 5 eager skills and tight path globs is fine. A project with 30 eager skills and a top-level `**/*` trigger is severe.
+
+| Configuration | Cache-write impact | Verdict |
+|---|---|---|
+| Description-only registry, lazy-fetch | minimal | optimal |
+| 5-10 eager skills, narrow path triggers | 5-10K | acceptable |
+| 30+ eager skills, broad triggers | 30-90K | refactor |
+| MCP server fully loaded, no gateway | varies, often 10K+ | mitigate via gateway |

package/core/anti-patterns/tool-call-spam.md

@@ -0,0 +1,93 @@
+---
+anti_pattern_id: tool-call-spam
+name: "Tool-call spam — Read repetition where Grep / batched ops would do"
+type: anti-pattern
+severity: MEDIUM
+hit_rate_impact: "indirect: tool-call inflation, output-token spike, latency"
+detection_method:
+  - measure-tokens (tool calls / turn > 1.5)
+  - session JSONL inspection for repeated Reads of the same file
+applies_to: ["all-tools-with-Read-Grep"]
+linked_rules:
+  - meta-discipline (5.1 read discipline)
+  - quality-gates (verify-after-changes)
+---
+
+# Anti-Pattern 06 — Tool-call spam
+
+## 1. What it is
+
+The orchestrator (or a role) calls many small tools in serial — repeated Reads on the same file, separate Reads instead of one Grep, sequential Bash calls instead of one chained command — when a smaller number of higher-leverage calls would suffice.
+
+```
+# WRONG — 5 Reads to find one config value
+Read("config/a.ts")  ; not here
+Read("config/b.ts")  ; not here
+Read("config/c.ts")  ; found!
+Read("config/c.ts")  ; re-read for context
+Read("config/c.ts")  ; re-read after edit
+
+# WRONG — 4 Bash calls instead of 1 chained
+Bash("git status")
+Bash("git diff")
+Bash("git log -5")
+Bash("git branch --show-current")
+
+# RIGHT
+Grep("MAX_RETRIES", path="config/", -n=true, -A=3, -B=1)
+Bash("git status; git diff; git log -5; git branch --show-current")
+```
+
+## 2. Why it kills cache
+
+Two failure modes compound:
+
+- **Per-call overhead**: every tool call adds the call's request + response to the conversation (cache-write next turn) plus invocation latency. Small tool calls have a high *fixed* cost relative to the information returned.
+- **Output-token spike**: high tool-call density usually correlates with the model narrating each step ("Now I'll read X…", "That didn't have it, let me check Y…"). Conductor's P1.5 baseline shows output tokens dominate cost (avg 667/turn, top turns 12K-19.7K), and tool-call spam is a primary cause.
+
+Reference numbers (Conductor P1.5):
+- Avg tool calls / turn = **0.61** (project baseline; well-disciplined)
+- P2 target = **0.43** (-30% reduction)
+- Anti-pattern threshold = **> 1.5/turn** sustained
+
+Per the baseline notes: "On average, 61% of turns contain at least one tool call. Total 22,917 tool calls across 37,763 turns." A session at 1.5/turn would have 56K tool calls, doubling tool-overhead cost.
+
+## 3. Detection
+
+```bash
+# Tool calls per turn (uses bundled measure-tokens.sh)
+bash tools/measure-tokens.sh --latest | grep -E 'tool calls'
+```
+
+**Code-level signal** in session JSONL:
+```bash
+# Count repeated Reads on the same file
+grep '"name":"Read"' <session>.jsonl | \
+  grep -oE '"file_path":"[^"]+"' | sort | uniq -c | sort -rn | head
+# Any file Read > 3 times = candidate for batching / Grep substitution
+```
+
+**Self-check (LLM)**: at any point in a turn where the third sequential Read on the same file is about to happen, stop and ask: "would Grep with -A/-B context have found this in one call?"
+
+## 4. Fix / Alternative
+
+**Three principles** (per `meta-discipline.md` §5.1):
+
+1. **Grep before Read** for symbol / value lookup. Use `-A` / `-B` / `-C` for surrounding context.
+2. **Range Read** when 50+ contiguous lines are genuinely needed (Anti-Pattern 02 fix).
+3. **Batch independent Bash calls** with `;` or `&&` chaining when they don't depend on each other.
+
+**Parallel-tool-calls rule**: when independent calls can run in parallel (e.g., `git status`, `git diff`, `git log` — none depends on the other's output), issue them in a single response with multiple tool invocations rather than serially across N turns.
+
+**Reference**: the originating workspace's `coding-conventions.md` codifies a Pre-Commit Checklist that runs typecheck + tests + build + review *in parallel where possible*. The same parallelism principle applies inside any single turn's tool calls.
+
+## 5. Severity rating
+
+**MEDIUM** — degrades efficiency without breaking correctness. A 2× tool-call density doubles latency and increases output-token cost ~40-60% (the model narrates more). Hit rate is unaffected directly, but session JSONL size grows faster.
+
+| Pattern | Tool calls / turn | Output tokens / turn | Verdict |
+|---|---|---|---|
+| Disciplined (Conductor baseline) | 0.6 | 670 | optimal |
+| Acceptable | 0.8 - 1.2 | 700 - 900 | tolerable |
+| Spam threshold | > 1.5 | > 1000 | refactor |
+| Severe | > 2.5 | > 1500 | active intervention |

package/core/docs-templates/CURRENT_WORK.md

@@ -0,0 +1,64 @@
+# CURRENT WORK — `<your-project>`
+
+> **What this is**: session continuity log. Updated EVERY session. Read FIRST every session start.
+> Lean (~150 lines). When it grows past, archive older sessions to `docs/sessions/<date>.md`.
+
+> **Status (P0 placeholder)**: replace this entire file with your project's first entry on first install. P1 will provide a more developed starter template.
+
+---
+
+## Session log
+
+### 2026-MM-DD — Session N
+
+**In progress**:
+- (current task with file paths)
+
+**Just completed**:
+- (last task shipped)
+
+**Issues / blockers**:
+- (anything stuck)
+
+**Next session should start with**:
+- (concrete first action)
+
+---
+
+### Template for new entries
+
+Copy and paste at the top of the section above:
+
+```
+### YYYY-MM-DD — Session NN
+
+**In progress**:
+- ...
+
+**Just completed**:
+- ...
+
+**Issues / blockers**:
+- ...
+
+**Next session should start with**:
+- ...
+```
+
+---
+
+## Project-level state (persistent across sessions)
+
+> Things that don't change every session but that any session needs to know.
+
+- **Current phase**: (e.g., "P3 — Implementation")
+- **Active branch**: (e.g., `feature/billing-live-activation`)
+- **Active feature flags**: (e.g., `IAP_ENABLED=false`, `AI_GATEWAY_ENABLED=true`)
+- **Known blockers**: (e.g., "payment-provider live activation pending business registration approval")
+- **Reference docs**: (links to `docs/PLANS.md`, `docs/REMAINING_TASKS.md`, `docs/specs/`)
+
+---
+
+## Session continuity rule
+
+CRITICAL: maintain CURRENT_WORK.md with in-progress tasks, issues, next steps for instant session resume. Never end a session without updating this file.

package/core/docs-templates/INDEX.md

@@ -0,0 +1,57 @@
+# INDEX — `<your-project>` document map
+
+> **What this is**: a single page that points to every other doc in `docs/`. Update when you add a doc.
+
+> **Status (P0 placeholder)**: customize on first install. P1 will provide a more developed example.
+
+---
+
+## Top-level docs
+
+| Doc | Purpose | Read frequency |
+|---|---|---|
+| `CURRENT_WORK.md` | Session continuity | Every session |
+| `REMAINING_TASKS.md` | Launch readiness dashboard | Per milestone |
+| `PLANS.md` | Phase roadmap | Per quarter |
+| `TASKS.md` | Active phase task tracker | Per task |
+| `INDEX.md` | This file — document map | When adding new doc |
+
+## Architecture
+
+| Doc | Purpose |
+|---|---|
+| `architecture/README.md` | System architecture overview |
+| `architecture/<adr>.md` | Per-decision ADRs |
+
+## Specs (per area)
+
+| Doc | Area |
+|---|---|
+| `specs/_example.md` | Template — DO NOT edit; copy + rename |
+| `specs/auth.md` | Authentication / authorization |
+| `specs/billing.md` | Payment / subscription |
+| `specs/email.md` | Email infrastructure |
+| `specs/<area>.md` | (add per area) |
+
+## Sessions (archive)
+
+| Doc | Purpose |
+|---|---|
+| `sessions/<date>.md` | Archived `CURRENT_WORK.md` content when it grew too long |
+
+## Reference / legal / compliance
+
+| Doc | Purpose |
+|---|---|
+| `legal/<doc>.md` | Legal copy (privacy, terms, etc.) |
+| `compliance/<doc>.md` | Audit / compliance notes |
+
+---
+
+## How to use
+
+When you create a new doc under `docs/`, add a row to the appropriate table in this file. If the table doesn't exist, create it.
+
+When a doc is archived or deleted, REMOVE its row (don't strikethrough — just delete).
+
+This file is the LANDING PAGE for any new contributor. Keep it scannable in 30 seconds.

package/core/docs-templates/PLANS.md

@@ -0,0 +1,44 @@
+# PLANS — `<your-project>`
+
+> **What this is**: long-term phase roadmap. Strategic — what major work remains and in what order.
+> Updated infrequently (per quarter / major milestone).
+
+> **Status (P0 placeholder)**: replace contents on first install.
+
+---
+
+## Phase summary
+
+| Phase | Name | Status | Target |
+|---|---|---|---|
+| **P0** | Foundation | ✅ done | YYYY-MM-DD |
+| **P1** | (e.g., Core auth + onboarding) | ⏳ in progress | YYYY-MM-DD |
+| **P2** | (e.g., Billing + payment) | ⏳ planned | YYYY-MM-DD |
+| **P3** | (e.g., Mobile parity) | ⏳ planned | YYYY-MM-DD |
+| **P4** | (e.g., Public launch) | ⏳ planned | YYYY-MM-DD |
+
+---
+
+## Phase detail template
+
+For each phase, document below with sections:
+
+```
+## P<n> — <name>
+
+**Goal**: one sentence.
+
+**Deliverables**:
+- [ ] item 1
+- [ ] item 2
+
+**Stop condition**: what proves the phase is done.
+
+**Risks**: known unknowns and mitigations.
+```
+
+---
+
+## Pause discipline
+
+If priorities shift mid-phase, pause without guilt. Document the pause reason in `docs/CURRENT_WORK.md`. PLANS.md is a target, not a contract.

package/core/docs-templates/README.md

@@ -0,0 +1,40 @@
+# `core/docs-templates/` — Universal doc template skeletons
+
+Tool-agnostic markdown templates that every CONDUCTOR-installed project gets at `docs/<file>.md`. The same files install regardless of which AI coding tool drives the project — adapters do NOT transform these (they are already universal).
+
+## What lives here
+
+| Template | Installed at | Purpose |
+|---|---|---|
+| `CURRENT_WORK.md` | `docs/CURRENT_WORK.md` | Session continuity. Always-load on session start. Lean (~150 lines max). |
+| `REMAINING_TASKS.md` | `docs/REMAINING_TASKS.md` | Launch readiness dashboard / open scope. |
+| `PLANS.md` | `docs/PLANS.md` | Long-term phase roadmap. |
+| `TASKS.md` | `docs/TASKS.md` | Phase completion tracker. |
+| `INDEX.md` | `docs/INDEX.md` | Document map — pointer to every other doc in `docs/`. |
+| `specs/_example.md` | `docs/specs/_example.md` | Spec template. User renames + duplicates per area (e.g., `auth.md`, `billing.md`). |
+
+## Why these are universal
+
+- They are plain markdown.
+- They reference no tool-specific syntax.
+- The same workflow phase definitions reference them regardless of tool.
+- The `Read first every session` instruction in adapter outputs always points to `docs/CURRENT_WORK.md`.
+
+## Why they aren't transformed by adapters
+
+Unlike `core/universal-rules/*` (which adapters re-emit with tool-specific front-matter), the doc templates are READ by every tool's chat session as plain markdown. No transformation needed.
+
+The adapter's job is just to COPY them into the target project's `docs/` directory if they don't already exist (idempotent — never overwrite).
+
+## Status (P0 foundation)
+
+All template files are PLACEHOLDERS. P1 fills them with starter content sanitized from the reference adopter.
+
+## Authoring guidance for P1
+
+Each template should:
+- Have a clear "What this is" header at the top.
+- Use ATX headings.
+- Include 1-2 example entries the user can immediately replace.
+- Be SHORT (~30-100 lines). These are templates; the user grows them.
+- Have NO project-specific names. Use generic placeholders (`<your-project>`, `<your-area>`).

package/core/docs-templates/REMAINING_TASKS.md

@@ -0,0 +1,43 @@
+# REMAINING TASKS — `<your-project>`
+
+> **What this is**: open scope dashboard. Things that need to ship before launch / before next milestone.
+> Updated when scope changes. NOT a daily task tracker (that's TASKS.md).
+
+> **Status (P0 placeholder)**: replace contents on first install. P1 fills with a more developed example.
+
+---
+
+## Launch readiness
+
+| Area | Status | Owner | Blocker |
+|---|---|---|---|
+| Auth flow | ⚠️ partial | (you) | (e.g., social login pending) |
+| Billing | ⏳ planned | (you) | (e.g., payment-provider live activation) |
+| Email infra | ✅ done | — | — |
+| Mobile parity | ⚠️ partial | (you) | (e.g., iOS push notifications pending) |
+| (add rows per area) | | | |
+
+---
+
+## Cross-cutting tasks
+
+- [ ] (e.g., "i18n sync — propagate pricing copy across 8 locales")
+- [ ] (e.g., "audit all `console.error` → migrate to `logError()`")
+- [ ] (e.g., "verify CSP headers on production")
+
+---
+
+## Deferred (post-launch)
+
+- [ ] (e.g., "bank-aggregator integration")
+- [ ] (e.g., "Spring Boot microservices migration")
+- [ ] (e.g., "GUI installer")
+
+---
+
+## How to use this file
+
+- One row per launch-blocking area.
+- Update status when it changes (⏳ planned / ⚠️ partial / ✅ done / ❌ blocked).
+- When all areas are ✅, you're launch-ready.
+- When a blocker resolves, mention it in `docs/CURRENT_WORK.md` session log.

package/core/docs-templates/TASKS.md

@@ -0,0 +1,51 @@
+# TASKS — `<your-project>`
+
+> **What this is**: phase completion tracker. Per-phase task list with concrete work items.
+> Updated as tasks complete.
+
+> **Status (P0 placeholder)**: replace contents on first install.
+
+---
+
+## Active phase: P<n> — <name>
+
+### Tasks
+
+- [ ] **Task 1** — short description
+  - File paths: `<web-app>/...`, `packages/shared/...`
+  - Stop condition: what proves done
+  - Owner / agent: (e.g., `@builder` Opus / human)
+- [ ] **Task 2** — short description
+  - File paths:
+  - Stop condition:
+  - Owner / agent:
+- [ ] **Task 3** — short description
+  - File paths:
+  - Stop condition:
+  - Owner / agent:
+
+---
+
+## Task entry template
+
+```
+- [ ] **Task <n>** — <short description>
+  - File paths: <list of paths to read/edit>
+  - Stop condition: <what proves done>
+  - Owner / agent: <e.g., @builder Opus / @helper Sonnet / human>
+```
+
+---
+
+## Completed (last 10)
+
+- [x] (move completed items here, newest at top)
+- [x] (older completed items archive to `docs/sessions/<phase>.md` when this section grows past 10)
+
+---
+
+## How this differs from `REMAINING_TASKS.md`
+
+- `REMAINING_TASKS.md` = high-level launch readiness dashboard (areas, not individual tasks).
+- `TASKS.md` = current phase's discrete tasks with file paths and stop conditions.
+- `CURRENT_WORK.md` = today's session: what's in progress right now.