| name | plan-task |
| description | Take rough free-text notes for a task and produce a structured task spec markdown ready for `/do-task`. Args: <notes_path> [<project_root>]. Reads the notes from the first path; if a project_root is given, ground the plan against THAT tree (read its CLAUDE.md, glob its files) — not the cwd. Prints the structured spec to stdout. Used by the task-orchestrator's "Plan it" form button. Can call AskUserQuestion when an ambiguity would otherwise force a wrong plan. |
plan-task
Take the user's rough notes (path passed as the first argument), inspect the target project enough to ground the plan in real files, and emit a structured task spec ready for /do-task to consume. Print the result to stdout. Do not edit files. The orchestrator captures stdout verbatim and shoves it into the form's body field — any wrapper characters end up visible in the textarea.
Arguments
- First arg (
notes_path) — required. Path to the user's rough notes (e.g. /tmp/plan-task-XXXX.md).
- Second arg (
project_root) — optional. Absolute path to the project the plan is about (e.g. /home/user/workspace/soli/crm). When present, you MUST ground all exploration there — your cwd is the orchestrator, not the target project, so any unqualified Glob/Read/Grep would scan the wrong tree. When absent, fall back to your cwd.
Step 1 — Read the input
Read the file at notes_path. Treat its contents as the user's rough idea — could be one line, could be a paragraph, could be a half-formed bullet list.
Step 2 — Ground the plan in the target project
Before drafting the spec, do a quick read of the target project (the second arg, if given; otherwise cwd) so the plan names real files:
- Read
<project_root>/CLAUDE.md (and any relevant per-directory <project_root>/app/<x>/CLAUDE.md) — these encode naming conventions, file layout, generators, and lint rules.
- Use
Glob with explicit path: <project_root> (or absolute patterns), Read with absolute paths, and Grep with path: <project_root> to confirm where similar features live. For a "coupons" feature in a Soli app, the canonical answers are <project_root>/app/models/coupon.sl, <project_root>/app/controllers/coupons_controller.sl, <project_root>/db/migrations/<TS>_create_coupons.sl, <project_root>/tests/coupons_controller_spec.sl, and a resources("coupons") line in <project_root>/config/routes.sl — confirm by listing siblings, don't assume.
- In the spec output, write paths relative to the project root (e.g.
app/models/coupon.sl — not the absolute version). The reader will be working inside the project, not the orchestrator.
- Don't read more than ~5 files. The goal is grounding, not implementation.
If a critical detail is genuinely ambiguous and would change the structure of the plan — not a stylistic preference, not something /do-task can decide later — call AskUserQuestion with 2–4 concrete options. The orchestrator routes the question to the form. Examples worth asking:
- "Is this a brand-new resource or an extension of an existing model?" (changes whether we generate or extend)
- "Should this go in the main app or in an existing engine under
engines/?"
Examples not worth asking (just pick the obvious one):
- "What field types should the model have?" — the user usually doesn't know yet; let /do-task surface specifics.
- "Should we write tests?" — yes, always, per CLAUDE.md.
Do not call write tools (Edit, Write, NotebookEdit). Do not run the test suite or the dev server. Do not push, commit, or branch.
Step 3 — Synthesize a structured spec
Output the markdown spec directly as your response — no code-fence wrappers (no ```md or ``` around the whole thing), no preamble (no "Here's the plan:"), no postscript (no closing remarks).
The spec must follow this shape, in this order:
- A first-line title heading:
# <SLUG-IF-OBVIOUS>: <one-line summary>
## Severity — one of critical | high | medium | low | n/a followed by an em-dash and a one-line why## Location — concrete file paths grounded in Step 2. List the files /do-task will create or change. Use (new) for files that don't exist yet. Only fall back to TBD — surface during /do-task when the change is genuinely placeless (e.g. a one-line config tweak whose location depends on /do-task's discovery).## Issue — 2–5 sentences describing the problem in the user's voice## Proposed Fix — 2–5 sentences describing the approach (concrete enough that /do-task can act on it; vague enough to leave room for the implementer to deviate). Mention the generator commands when applicable (soli generate model coupon, soli generate controller coupons, etc.) — they encode the framework's expected boilerplate.## Acceptance Criteria — 3–5 bullets, each testable
Constraints
- Never use
pkill, kill, killall, or any process-killing command.
- Output only the markdown spec. No "Here's the plan:", no trailing summary. The orchestrator captures stdout verbatim and shoves it into the form's body field.
- Only use a
SLUG- prefix in the title if the notes name one (e.g. SEC-123, COV-014, BUG-007). Otherwise omit and write just # <one-line summary>.
- Preserve any file paths, function names, or line numbers the user wrote — copy them into the Location section verbatim. Augment with the paths you discovered in Step 2.
- 3–5 acceptance-criterion bullets is the sweet spot. Each should be testable.
- No timestamps in migration filenames — use
<TS> as a placeholder (the generator fills in the real timestamp).
Examples
Input (notes file):
add coupons
Output (everything between the dashed lines, no fences, that's the literal output):
Add coupons resource
Severity
medium — new feature; isolated to its own files
Location
- app/models/coupon.sl (new)
- app/controllers/coupons_controller.sl (new)
- app/views/coupons/index.html.slv (new)
- app/views/coupons/show.html.slv (new)
- app/views/coupons/new.html.slv (new)
- app/views/coupons/edit.html.slv (new)
- app/views/coupons/_form.html.slv (new)
- db/migrations/_create_coupons.sl (new)
- config/routes.sl — add
resources("coupons")
- tests/coupons_controller_spec.sl (new)
Issue
The app needs a Coupons resource: somewhere to model promotional codes, a place to list/create/edit them, and persistence. The user has no existing scaffold for this.
Proposed Fix
Run /soli-resource coupons (or step through soli generate model coupon / soli generate controller coupons / soli generate migration create_coupons) to scaffold the canonical RESTful resource. Fill in the model fields (at minimum: code, discount_pct, expires_at, active), validations (code presence + uniqueness), and the controller's _permit_params whitelist. Add resources("coupons") to config/routes.sl. Cover the controller end-to-end in the spec file (>90% coverage per CLAUDE.md).
Acceptance Criteria
Coupon model exists with code, discount_pct, expires_at, active fields and presence + uniqueness validation on codeCouponsController provides index/show/new/create/edit/update/destroy, all whitelisting params via _permit_paramscoupons migration runs cleanly forward and backward (soli db:migrate up / down)- Controller spec covers happy paths and validation failures, hitting >90% coverage on the new code
coupons_path() / coupon_path(c) helpers resolve from resources("coupons") and replace any hand-built URLs in views
Input (notes file):
csrf middleware doesn't strip x-forwarded-host before computing origin for double-submit token. attacker can pin a fake origin and bypass.
src/middleware/csrf.rs around line 80
Output:
SEC-?: CSRF middleware honours X-Forwarded-Host without trust check
Severity
high — origin-based CSRF check can be spoofed via attacker-controlled header
Location
- src/middleware/csrf.rs around line 80
Issue
The CSRF double-submit token check derives the request origin from X-Forwarded-Host. When the app is reachable directly (no trusted proxy), an attacker can set that header on a forged request and pin a same-origin value, defeating the check.
Proposed Fix
Gate X-Forwarded-Host consumption on the existing enable_trust_proxy flag — when that flag is off, fall back to the bare Host header, ignoring proxy hints. Add a regression test that calls the middleware twice (proxy on / off) with the same forged header and asserts the off-case rejects.
Acceptance Criteria
- CSRF middleware ignores
X-Forwarded-* when enable_trust_proxy is false
- Test asserts a forged
X-Forwarded-Host does not satisfy origin check with proxy off
- Test asserts the trusted-proxy path still works as before
- No new public API surface; the change is internal to
csrf.rs
