ce-plan

Files (35)

• SKILL.md
• agent-native-planning-strategist.md · references/agents/
• architecture-strategist.md · references/agents/
• best-practices-researcher.md · references/agents/
• data-integrity-guardian.md · references/agents/
• data-migration-reviewer.md · references/agents/
• deployment-verification-agent.md · references/agents/
• framework-docs-researcher.md · references/agents/
• git-history-analyzer.md · references/agents/
• learnings-researcher.md · references/agents/
• pattern-recognition-specialist.md · references/agents/
• performance-oracle.md · references/agents/
• repo-research-analyst.md · references/agents/
• security-sentinel.md · references/agents/
• slack-researcher.md · references/agents/
• spec-flow-analyzer.md · references/agents/
• web-researcher.md · references/agents/
• approach-altitude.md · references/
• deepening-workflow.md · references/
• final-review.md · references/
• html-rendering.md · references/
• intake.md · references/
• markdown-rendering.md · references/
• plan-handoff.md · references/
• plan-sections.md · references/
• reasoning-elevation.md · references/
• research.md · references/
• resume.md · references/
• settled-decisions.md · references/
• structure.md · references/
• synthesis-summary.md · references/
• universal-planning.md · references/
• context.mjs · scripts/
• elevation-dispatch.sh · scripts/
• peer-job-runner.py · scripts/

SKILL.md (first lines)

# Create Technical Plan

**Note: The current year is 2026.** Use this when dating plans and searching for recent documentation.

**Outcome:** a durable plan artifact an implementer can start from confidently, handed off through the Phase 5.4 menu. `ce-brainstorm` defines **WHAT** to build as a requirements-only unified plan; `ce-plan` enriches that same artifact with **HOW**; `ce-work` executes it. A prior brainstorm is useful context but never required — any input works: a requirements-only unified plan, a legacy requirements doc, a bug report, a feature idea, or a rough description.

**When directly invoked, always plan.** Never classify a direct invocation as "not a planning task" and abandon the workflow. If the input is unclear, ask clarifying questions or use the planning bootstrap to establish enough context — but always stay in the planning workflow.

**Research, decide, and write the plan — never implement.** This workflow does not write production code, run tests, or learn from execution-time results; if the answer depends on changing code and seeing what happens, that belongs in `ce-work`. Directional pseudo-code and DSL grammar sketches that communicate design remain welcome where the references allow them — the boundary is implementing, not sketching.

## Setup

Run this once at the start of this invocation, before any subagent dispatch, and follow the directives it prints — except where one conflicts with this skill's own rules on asking the user questions, whether those rules are scoped to a non-interactive mode or apply in every mode, in which case this skill's rules win and no blocking question is asked. Run the fence exactly as written, as its own command: do not pipe or filter it (no `head`, `tail`, or `grep`), do not truncate its output, and do not bundle it into a batch with other commands. Its output opens with a `=== skill context` header and ends with `CE_CONTEXT_END`; if you received one of those lines without the other, the output was truncated — rerun the fence verbatim once. That recovery is the only rerun: otherwise do not rerun it within the same invocation; a later invocation of this or any other skill runs its own. If no Node runtime is available the skill proceeds unchanged.

```bash
SKILL_DIR="<absolute path of the directory containing the SKILL.md you just read>";
NODE="$(for c in node nodejs; do command -v "$c" >/dev/null 2>&1 && "$c" -e '' >/dev/null 2>&1 && { echo "$c"; break; }; done)";
if [ -n "$NODE" ]; then
"$NODE" "$SKILL_DIR/scripts/context.mjs" || echo "context script failed; continue with the skill's normal behavior";
else
echo "no Node runtime; continue with the skill's normal behavior";
fi
```

## Mandatory Completion Contract

Every normal interactive `ce-plan` branch that produces a plan artifact or checkpoint is incomplete until its owning handoff question is presented. For software implementation-plan runs that continue past Phase 0.1b, that boundary is Phase 5.4's post-generation handoff menu. Non-software plan-seeking and approach-altitude branches use the terminal handoff in the reference workflow they route to; do not force those branches through Phase 5.4 after they have been told to skip subsequent phases. Answer-seeking is the exception: it may end after delivering the answer unless the universal-planning reference says to offer save/share.

For software implementation-plan runs, writing the plan file, running the confidence check, and running or skipping `ce-doc-review` are intermediate milestones, not completion. This remains true when the user's prompt says only "create a plan", "write the doc", "run `ce-doc-review`", or similar. The only exception is pipeline mode (LFG or any `disable-model-invocation` context), where the caller owns the next step after the plan file, confidence check, and non-interactive document review are complete.

Before any response that could end a software implementation-plan run, verify that the plan path is known, the non-interactive review state or documented skip state is summarized, and the user has been asked: "Plan ready at `<absolute path to plan>`. What would you like to do next?" If the menu fits the platform's blocking-question tool, ask it there; otherwise render the numbered handoff options in chat and wait. If the user selects an action, execute the Phase 5.4 routing for that selection before treating the skill as complete.

## Interaction Method

When asking the user a question, use the platform's blocking question tool: `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex, `ask_question` in Antigravity CLI (`agy`), `ask_user` in Pi (requires the `pi-ask-user` extension). Fall back to numbered options on the host's user-visible chat surface only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question.

Ask one question at a time. Prefer a concise single-select choice when natural options exist.

The **feature description** is the input this skill was invoked with — what to plan, present in the current prompt or conversation, whether the user provided it directly or a calling skill passed it (e.g. `lfg` in `mode:pipeline`). If the input is present but unclear, do not abandon the workflow — ask one or two clarifying questions, or proceed to the planning bootstrap. If none was provided at all, ask: "What would you like to plan? Describe the task, goal, or project you have in mind." Then wait for their response before continuing.

## Artifact Root

**Every file reference inside the plan document is repo-relative** (`src/models/user.rb`), never absolute — unit file lists, pattern references, origin links, and prose mentions alike. Absolute paths break portability across machines, worktrees, and teammates. Paths printed to the user in chat are the exception and stay absolute so they are clickable.

This skill writes plans under `<root>/plans/` and reads learnings under `<root>/solutions/`. Resolve `<root>` when you first compose a `<root>/` path, never before you need it. A write to `<root>/...` and a read of `<root>/solutions/` both count, so either one triggers resolution; only a run that touches no `<root>/` path at all — a scratch-only or no-repo flow — skips it. Pass the resolved path to any subagent, not the config.

<!-- ce-docs-root:start -->
**Resolve the CE artifact root `<root>` before composing any artifact path.**

- **Read** `docs_root` from `<repo-root>/.compound-engineering/config.yaml` only (`<repo-root>` = `git rev-parse --show-toplevel`). Do not read it from `config.local.yaml`. Unset -> `<root>` is `docs`, exactly as before.
- **Validate** a set value: a repo-relative directory whose real, symlink-resolved path stays inside the repo and is neither the repo root nor under `.git/`. Otherwise stop with an error naming `docs_root` and the value -- never fall back to `docs`.
- **Use** `<root>` as the sole artifact location: create it if absent, compose each path as `<root>/<subdir>` with this skill's own subdirectory, and never also read `docs`.
<!-- ce-docs-root:end -->

## Task Visibility

After intake determines that `ce-plan` will perform a material multi-stage run, use the platform's task-tracking capability when available to show a short user-facing view derived from the selected route and remaining planning work. Track meaningful outcomes, not every phase, tool call, or microstep; add conditional work only when its gate fires, and update the view at meaningful transitions. Use short, outcome-led names. If no task-tracking capability is available, continue normally without simulating a task list in chat.

## Workflow

Phases run in order, except where a phase routes you out of the sequence: the Phase 0.1 resume and deepen fast paths short-circuit to Phase 5.3, Phase 0.1a holds at the approach, and Phase 0.1b hands non-software work to `references/universal-planning.md`. Once a phase tells you to skip subsequent phases, skip them. Each phase below names the reference that carries it; read that reference before starting the phase it names.

### Phase 0: Resume, Source, and Scope

#### 0.0 Resolve Output Mode

Determine `OUTPUT_FORMAT` before any other phase fires. Output mode is **exclusive** — the plan is written as either markdown (`.md`) OR HTML (`.html`), never both. Precedence: in-prompt request > user-stated preference > config > default (`md`), with a hard pipeline-mode override.

1. **In-prompt request.** Reason over the user's prompt for this run for a request about *this document's* output format, expressed either as the `output:` shorthand or in plain language ("make the plan a webpage"). Match an explicit format case-insensitively to `md`/`html`, and ignore the `output:` token when reading the rest of the prompt as the feature description. Distinguish a request about the document's format from a format named as subject matter: "add an HTML export feature" is the work, not a doc-format request.
   - `output:` alone (no value) → no-op, fall through to step 2.
   - `output:<unknown>` (e.g., `output:pdf`) → drop the token, fall through, and emit a one-line note above the post-generation menu after final resolution: `Ignored unknown output: value '<value>' — using <resolved_format> instead.` Do not hardcode `md` in the note — that misleads users when config has set HTML.
2. **User-stated preference.** If this prompt holds no format request, honor an output-format preference the user established earlier that is already in your context, matching `md`/`html` case-insensitively. A remembered preference is more current than the rarely-edited config, so it **overrides** the config in step 3. Do not open or search instruction files to find it.
3. **Config.** Apply the ordinary-key rule below: the first **active (non-commented)** `plan_output:` matching `md` or `html` (case-insensitively) wins. Missing, invalid, or commented values continue to the next layer, then step 4. The shipped template's commented examples are not settings.
4. **Default.** Otherwise `OUTPUT_FORMAT=md`. If `<repo-root>` cannot be resolved so the config cannot be read, fall through to this default rather than failing.
5. **Pipeline override.** When invoked from LFG or any `disable-model-invocation` context, force `OUTPUT_FORMAT=md` regardless of steps 1-4.

**Token-parsing convention:** only literal-prefix flag tokens (`output:`, `mode:`, the exact `confirm:auto`/`confirm:ask` forms, `plan_model:<alias>`, `delegate:` where applicable) are consumed and stripped. Other `<word>:<word>` tokens — including commit prefixes like `feat:` and any unrecognized `confirm:<value>` — pass through verbatim into the feature description. A stripped `plan_model:<alias>` carrier is retained for the Phase 5.2 model-elevation step.

**Load the format-rendering reference for the resolved value:** `references/markdown-rendering.md` when `OUTPUT_FORMAT=md`, `references/html-rendering.md` when `OUTPUT_FORMAT=html`. Section content is the same either way; presentation differs. Both are paired with `references/plan-sections.md`.

<!-- ce-config-layers:start -->
**Resolve ordinary CE yaml keys from the two repo files.**

- **Read** `<repo-root>/.compound-engineering/config.local.yaml`, then `config.yaml` (`<repo-root>` = `git rev-parse --show-toplevel`). Missing files are skipped. Gitignore does not change resolution.
- **Win** with the first active (non-commented) value. For scalars, empty is unset; an invalid value continues to the next layer, then the skill default. For lists and maps, a present key — including an empty list or map — replaces the whole key.
- **Do not** use this rule for `docs_root` — that key is `config.yaml` only.
<!-- ce-config-layers:end -->

Also resolve `SKIP_SCOPING_CONFIRM` here by the same precedence. `confirm:auto` skips the scoping-synthesis confirmation for this run and `confirm:ask` forces it on; honor an equivalent plain-language instruction the same way ("just write it, don't ask me to confirm" skips; "ask me before writing the plan" asks). Only those two literal values are consumed as a flag — any other `confirm:<value>` stays verbatim in the feature description. Then a preference already in your context, then the first **active (non-commented)** `plan_skip_scoping_confirm:` matching `true` or `false`, then the default of asking. `references/intake.md` owns what the skip does and does not cover, at the gate it applies to.

#### 0.1 Resume Existing Plan Work When Appropriate

Read `references/resume.md` before acting on this phase; it carries the deepen-intent triggers, the extension-then-frontmatter routing table, and the format-preservation rules. This check needs `<root>/plans/`, so it only applies to a repo-backed run — if there is no git repository or `<root>` fails to resolve, skip resume discovery and continue to Phase 0.1a rather than failing the run. When a plan path was given explicitly, use it directly without resolving `<root>` — the skip never discards a path the user named.

If the user references an existing plan file or an obvious recent match exists in `<root>/plans/`, read it and confirm whether to update it in place or create a new plan.

**A requirements-only unified plan is not a resume target.** A `<root>/plans/` file with `artifact_readiness: requirements-only` is an *enrichment input* — do **not** fire the update-or-create confirm for it. Fall through to Phase 0.2, which enriches it in place. In pipeline mode the resume choice is made automatically (default to in-place update of the referenced plan) and is never prompted, because no user is present to answer.

Normal editing requests ("update the test scenarios", "add an implementation unit") follow the standard resume flow rather than the deepening fast path.

#### 0.1a Recognize Approach-Altitude Requests

Some requests are better answered one level up: produce a grounded approach-plan — a plan for *how the deliverable will be made* — and hold there. This runs after Phase 0.1's fast paths and before Phase 0.1b's domain split.

Two entries. **Explicit is always honored**: when the user asks for the approach itself ("plan the approach", "plan how you'd do X", "don't do it yet — just plan how you'd approach it"), enter approach altitude and hold there; do not begin the deliverable. **Proactive is rare**: offer only when method uncertainty and the cost of getting it wrong are *both* clearly high, as a single dismissible line naming the signal — never a blocking question. If either is low, or it is borderline, stay silent and plan normally; cost alone never fires the offer, and a large but method-obvious change is not method uncertainty. An investigative request with no approach-language passes through this gate untouched to Phase 0.1b.

`references/resume.md` carries the full entry conditions and the boundaries against the other approach surfaces. On entry, read `references/approach-altitude.md` and follow it. Otherwise continue to Phase 0.1b unchanged.

#### 0.1b Classify Task Domain

If the task asks to build, modify, refactor, deploy, or architect software (code, schemas, infrastructure), continue to Phase 0.2.

Classify by task-type, not topic. A request that merely *references* code, a repo, an API, or a database is not automatically software work: building or modifying code is software; investigating or analyzing it is answer-seeking. If the domain is genuinely ambiguous, ask the user before routing.

Otherwise, read `references/universal-planning.md` and follow that workflow instead. Skip all subsequent phases. Named tools or source links don't change this routing — they're inputs.

**Honor user-named resources (Core Principle 8).** When the user names a specific resource — a CLI, MCP server, URL, file, doc link, or prior artifact — treat it as authoritative input, not a suggestion. Discover it if unknown (`command -v`, fetch, read) before assuming it is unavailable, and use it in place of generic alternatives. If it fails or does not exist, say so explicitly rather than silently substituting. The remaining core principles and the plan quality bar are in `references/intake.md`.

#### 0.2–0.7 Source, Bootstrap, Depth, and Scoping

From Jehu/a0_compound_engineering, MIT.

More from Jehu/a0_compound_engineering