devlyn-cli 1.15.0 → 2.1.0

package/config/skills/devlyn:ideate/references/elicitation.md

@@ -0,0 +1,97 @@
+# Elicitation flow (canonical body)
+
+Per-engine adapter prepended at runtime. This file is engine-agnostic.
+
+<role>
+You drive a focused conversation with a user who has an idea but not an engineering spec. Your job is to ask the right questions — not many questions — until a verifiable spec exists. The user does not know context engineering; assume they will under-specify and over-assume. You compensate by asking the specific decisions they did not realize they were making.
+</role>
+
+<input>
+- The user's initial goal text (free-form, possibly ambiguous).
+- The codebase (read-only) — for grounding inferred defaults.
+- `references/spec-template.md` — the shape of the output.
+- `_shared/expected.schema.json` — the shape of `spec.expected.json`.
+</input>
+
+<conversation_rules>
+1. Ask 1-2 questions per turn. More than that overwhelms the user and produces shallow answers.
+2. Questions are concrete and decision-grade. Bad: "what should the UX look like?" Good: "should `--lang fr` exit 1 with the rejected code in the error message, or fall back silently to English?"
+3. When the answer is obvious from context, infer the default and ask "I'll assume X — okay?" instead of asking the user to choose. Defaults free up the user's attention for decisions that actually matter.
+4. Track what is filled and what is missing in your running draft at `.devlyn/ideate-draft.md`. Update after each turn.
+5. Stop when the structural lint passes AND the user explicitly confirms ("looks good", "ship it", etc.). Hard ceiling: 8 turns total. Beyond that, the task is too large for ideate — recommend `--project` mode and stop.
+6. Do not save the conversation. The output is the spec.
+</conversation_rules>
+
+<missing_decisions_to_surface>
+For most coding tasks, the under-specified blanks are:
+
+1. **Input shape**: what does the user invoke to trigger the feature? Exact CLI command, HTTP request, function call?
+2. **Output shape**: what does success look like? Exit code, stdout substring, file existence, JSON shape?
+3. **Failure shape**: what happens on bad input? Exit code, error message format, fallback behavior (silent vs visible)?
+4. **Scope boundary**: which files are in-scope, which are out-of-scope? "Don't touch the auth module" is a boundary worth surfacing.
+5. **Constraints**: dependency policy (new deps allowed?), silent-catch policy, type-system escape policy, test coverage expectations.
+6. **Verification**: how does the user know it worked? Pick the smallest concrete check.
+
+Walk through these in roughly this order. Skip the ones already clear from the user's initial text.
+</missing_decisions_to_surface>
+
+<spec_kind_inference>
+Infer `spec.kind` from the user's framing:
+
+- "explore", "investigate", "I'm not sure if X is possible", "let's see what works" → spike. Confirm with: "I'll mark this as a spike — deliverable is learning, not production code. Sound right?"
+- "prototype", "rough version", "show me what it would look like" → prototype.
+- Default: feature. The user wants production-quality work.
+
+Do not ask "is this a feature, spike, or prototype?" — the user does not know the difference. Infer and confirm in one line.
+</spec_kind_inference>
+
+<draft_spec>
+Maintain `.devlyn/ideate-draft.md` after every user turn. Include:
+- Latest version of all 6 sections (Frontmatter, Context, Requirements, Constraints, Out of Scope, Verification).
+- "TODO" markers for sections still missing pieces.
+- A "decisions log" comment at the bottom listing what each turn settled.
+
+When you're about to ask the user a question, look at the draft first — if the answer is already discoverable from the initial goal + codebase, infer it instead of asking.
+</draft_spec>
+
+<lint>
+Before declaring the spec ready, verify structurally:
+- Frontmatter has `id`, `title`, `kind`, `status: planned`.
+- All 5 H2 sections present (`## Context`, `## Requirements`, `## Constraints`, `## Out of Scope`, `## Verification`).
+- Requirements ≥ 1 bullet.
+- Verification has either ≥ 1 named command OR the explicit pure-design escape phrase.
+
+If the lint fails, fix the missing piece (ask one focused question if needed) before announcing.
+
+After lint passes, also run `python3 .claude/skills/_shared/spec-verify-check.py --check <spec-path>` to validate the verification carrier shape. If exit 2: read the stderr message, fix the carrier, re-run. Exit 0 = ready.
+</lint>
+
+<output>
+Two files in `<spec-dir>/<id>-<slug>/`:
+- `spec.md` (per template).
+- `spec.expected.json` (per `_shared/expected.schema.json`).
+
+Final announcement (one line): `spec ready — /devlyn:resolve --spec <spec-path>`.
+
+Do NOT include the conversation transcript in the output. The spec stands alone.
+</output>
+
+## Quick mode (1Q) — single-turn assume-and-confirm
+
+When `--quick` is set:
+
+1. AI synthesizes spec from the one-line goal — fill every section with the most reasonable inference.
+2. AI presents the spec to the user with an explicit `## Assumptions made` block listing every inferred decision (one bullet each).
+3. User responds with "go" / "fix X to be Y" / "no, different".
+4. On "go": write the spec + spec.expected.json, run lint, announce.
+5. On "fix X": apply correction, re-present, ask again. Maximum 3 correction rounds before escalating to default mode.
+
+Quick mode trades thoroughness for speed. Use it for trivial-medium tasks where the user has a clear-enough goal that one round of inference + correction is sufficient.
+
+## Anti-patterns
+
+- Walls of questions in one turn.
+- Open-ended "what would you like" questions when the user clearly does not know.
+- Adding "for future flexibility" or "just in case" sections to the spec — the user did not ask for those, and the principles binding `/devlyn:resolve` reject them.
+- Saving the conversation transcript alongside the spec.
+- Stalling when the user gives a vague answer — re-ask with a more specific shape ("should it be A, B, or other?") rather than re-asking the same question.

package/config/skills/devlyn:ideate/references/from-spec-mode.md

@@ -0,0 +1,54 @@
+# `--from-spec` mode
+
+Per-engine adapter prepended at runtime.
+
+<role>
+The user already wrote a spec (or has one from elsewhere — a teammate, a previous project, a copy-paste from a doc). Your job is to lint and normalize it to the canonical shape — without reshaping the user's substantive intent.
+</role>
+
+<input>
+- `<path>` — the external spec markdown file.
+- `_shared/expected.schema.json` — the schema for the sibling `spec.expected.json`.
+- `references/spec-template.md` — the canonical shape.
+</input>
+
+<allowed_changes>
+You may:
+1. Add missing frontmatter fields (id from filename, kind=feature default, status=planned).
+2. Rename non-canonical section headings to canonical (`## Goals` → `## Requirements`, `## Notes` ignored unless they clearly belong in Constraints).
+3. Add a missing `## Out of Scope` section with `- (no explicit non-goals provided by author)`.
+4. Add a missing `## Verification` section if Requirements imply observable runtime checks — best-effort one-command-per-Requirement, then surface to user for review.
+5. Generate `spec.expected.json` from the `## Verification` block if the file is absent.
+6. Fix structurally invalid `spec.expected.json` (malformed JSON, missing required keys per `_shared/expected.schema.json`).
+</allowed_changes>
+
+<forbidden_changes>
+You must NOT:
+- Reshape Requirements content. The user's substantive intent is preserved verbatim.
+- Add new Constraints the user did not write.
+- Move items between Requirements and Out of Scope.
+- "Improve" the prose in Context. Author voice stays.
+- Add `## Assumptions` or `## Open questions` sections — that is default-mode work, not normalization.
+</forbidden_changes>
+
+<flow>
+1. Read `<path>`. Parse frontmatter. Identify present sections.
+2. Lint structurally (same checks as default mode).
+3. For each missing/malformed piece: apply the smallest allowed fix.
+4. Write the normalized spec. Default location: `<spec-dir>/<id>-<slug>/spec.md`. With `--in-place` flag: write to `<path>` directly (overwrites the original).
+5. Generate or fix `spec.expected.json` per the rules above. Same dir as the spec.
+6. Run `python3 .claude/skills/_shared/spec-verify-check.py --check <spec-path>` to validate.
+7. If lint still fails after allowed fixes (e.g. Requirements section is empty in the source), surface the issue and exit non-zero — do NOT invent Requirements.
+</flow>
+
+<output>
+Same as default mode: `<spec-dir>/<id>-<slug>/spec.md` + `<spec-dir>/<id>-<slug>/spec.expected.json`.
+
+Final announcement: `spec normalized — /devlyn:resolve --spec <spec-path>`. If the spec was lint-passing with no changes needed, announce: `spec already canonical — /devlyn:resolve --spec <spec-path>`.
+
+If lint failed unfixably: print the specific failure, exit non-zero. Do not write a partial output.
+</output>
+
+<rationale>
+`--from-spec` exists for power users with external context. Adding friction by forcing them through default-mode elicitation defeats the purpose. The mode trades elicitation depth for normalization speed; the user accepts that any author-side under-specification stays under-specified.
+</rationale>

package/config/skills/devlyn:ideate/references/project-mode.md

@@ -0,0 +1,76 @@
+# `--project` mode
+
+Per-engine adapter prepended at runtime.
+
+<role>
+The user wants to build a project, not a single feature. Your job is to elicit the project description, decompose it into 3-7 independently-shippable features, and write `plan.md` (the index) plus one spec.md + spec.expected.json per feature.
+</role>
+
+<conversation_rules>
+1. Project elicitation warrants more turns than single-spec mode. Hard ceiling: 12 turns instead of 8.
+2. Ask the same question categories as default mode (input/output/failure/scope/constraints/verification) but at the project level first, then drill into each feature.
+3. Decompose into 3-7 features. Fewer = the project is actually one big feature; recommend default mode. More = the project is too large; recommend splitting into separate ideate runs.
+4. Each feature must be independently shippable: a feature whose verification depends on another feature's runtime behavior is a dependency, not a feature.
+</conversation_rules>
+
+<decomposition_rules>
+- Features should be vertically sliced (full stack of one user-facing capability), not horizontally sliced (a layer that other features will need to consume).
+- A feature whose ONLY value is enabling other features (pure infrastructure) belongs in the first feature that needs it OR as an explicit "enabling spec" with the dependent feature waiting on it.
+- Feature dependencies are explicit in `frontmatter.depends_on`. The plan's suggested implementation order respects topological dependency.
+- Aim for features that take 1-3 hours of `/devlyn:resolve --spec` work each. Larger → split. Trivial → merge with neighbor.
+</decomposition_rules>
+
+<plan_md_shape>
+Output `<spec-dir>/plan.md`:
+
+```markdown
+# <Project name>
+
+## Goal
+
+2-4 sentences from the elicitation — what the project delivers and why.
+
+## Decomposition rationale
+
+1-2 paragraphs explaining how the project was sliced into features. Includes the order rationale.
+
+## Feature specs
+
+| ID | Title | Depends on | Status |
+|----|-------|-----------|--------|
+| <id-1> | ... | (none) | planned |
+| <id-2> | ... | <id-1> | planned |
+| ... | ... | ... | ... |
+
+## Suggested implementation order
+
+1. `/devlyn:resolve --spec <spec-dir>/<id-1>/spec.md`
+2. `/devlyn:resolve --spec <spec-dir>/<id-2>/spec.md`
+3. ...
+
+The order respects `depends_on`. Topologically equivalent specs can be parallelized later (Mission 2 work); single-task L1 ships them sequentially.
+
+## Project-level constraints
+
+Anything binding all features (e.g. "no new top-level dependencies", "all CLI output must support `NO_COLOR`"). Each feature spec inherits these in its Constraints section.
+```
+
+`plan.md` is the **index**, not a hidden dependency. `/devlyn:resolve` reads only the spec it is invoked with; it does not parse `plan.md`.
+</plan_md_shape>
+
+<output>
+- `<spec-dir>/plan.md` (the index above).
+- `<spec-dir>/<id-N>/spec.md` for each feature (per `references/spec-template.md`).
+- `<spec-dir>/<id-N>/spec.expected.json` for each feature (per `_shared/expected.schema.json`).
+
+Each per-feature spec is structurally lint-validated using `python3 .claude/skills/_shared/spec-verify-check.py --check <spec-path>`.
+
+Final announcement: `project ready — N specs at <spec-dir>/. Start with /devlyn:resolve --spec <first-spec-path>`.
+</output>
+
+<anti_patterns>
+- Decomposing into more features than the project needs (10+ features for a CLI). Project mode is for genuine multi-feature work.
+- Hidden coupling between features (feature B's spec assumes feature A's internal data structure). Surface as `depends_on` or fold into one spec.
+- Vision documents, roadmaps as separate tiers, market-positioning paragraphs. The locked design is index + specs. Anything else is context pollution.
+- Continuing past 12 turns of elicitation. If the project is still not clear at turn 12, recommend the user split it into 2-3 separate ideate runs.
+</anti_patterns>

package/config/skills/devlyn:ideate/references/spec-template.md

@@ -0,0 +1,102 @@
+# Canonical spec template
+
+The shape `/devlyn:ideate` writes and `/devlyn:resolve --spec` consumes. Single source of truth for spec structure.
+
+## Frontmatter
+
+```yaml
+---
+id: "<spec-id>"          # kebab-case, unique per spec-dir; auto-generated if user omits
+title: "<short title>"    # one line, descriptive
+kind: feature             # feature | spike | prototype
+status: planned           # planned → in_progress → done. ideate writes "planned"; resolve's CLEANUP flips to "done".
+depends_on: []            # list of spec ids this depends on (empty for standalone). project mode populates this.
+---
+```
+
+## `# <title>`
+
+Top-level heading repeats the title.
+
+## `## Context`
+
+2-4 sentences answering "why does this exist." User-facing motivation, not implementation detail. Traceable to whatever the user said during elicitation.
+
+## `## Requirements`
+
+Checklist of testable, scoped statements. Each bullet is one observable behavior:
+
+```markdown
+- [ ] `node bin/cli.js doctor` exits 0 on a clean machine.
+- [ ] `--verbose` lists installed plugins by name.
+- [ ] Exit code is `1` when any FAIL line appears.
+```
+
+Rules:
+- Each Requirement is independently verifiable (a command, a test, a file existence check).
+- Avoid implementation language ("use a try/catch") in Requirements; that goes in Constraints.
+- Pure-design Requirements are allowed (e.g. "follow the existing pattern in `lib/X.js`") but mark them "design-only" so Verification can be omitted for that bullet.
+
+## `## Constraints`
+
+Concrete rules with reasoning. Examples:
+
+```markdown
+- **Zero new npm dependencies.** Use only Node.js built-ins.
+- **No silent error catches.** Errors must be visible to the user with actionable messages.
+- **Touch only `bin/cli.js` and `tests/cli.test.js`.** Other files are out of scope.
+```
+
+Each constraint has a one-line "why" — bare constraints invite negotiation; reasoned constraints lock the contract.
+
+## `## Out of Scope`
+
+Explicit "must NOT build" list. Examples:
+
+```markdown
+- Auto-repair (report only).
+- Checking remote/registry state.
+- Refactoring the argument parser.
+```
+
+If the spec is small enough that nothing meaningful is out of scope, write `- (nothing notable; see Constraints for boundary)`.
+
+## `## Verification`
+
+Concrete commands or tests whose expected behavior names the success condition:
+
+```markdown
+- `node bin/cli.js doctor` exits 0; output contains `doctor:`.
+- `HOME=/nonexistent node bin/cli.js doctor` exits 1; output mentions `/nonexistent`.
+- `node --test tests/cli.test.js` passes.
+- `git diff -- package.json` is empty.
+```
+
+The body of the section reads humanely; the machine-readable contract lives in `spec.expected.json` (sibling file). Each command in this section maps to one entry in `spec.expected.json.verification_commands`.
+
+If all Requirements are pure-design (no observable runtime check), the body of this section is a single line: `- (all Requirements are pure-design; no runtime verification commands)`.
+
+## Sibling file: `spec.expected.json`
+
+Schema: `_shared/expected.schema.json`. Required when Requirements have observable checks; optional when all Requirements are pure-design.
+
+Generated by ideate from the conversation:
+- `verification_commands` ← parsed from `## Verification` body + any commands the conversation surfaced.
+- `forbidden_patterns` ← from Constraints that mention specific anti-patterns ("no silent catches", "no any types").
+- `required_files` / `forbidden_files` ← from Out of Scope and Requirements.
+- `max_deps_added` ← from Constraints (default 0 unless the spec licenses a new dep).
+
+## Quality bar (lint enforces structurally; ideate enforces substantively)
+
+Structural (lint):
+- Frontmatter valid + required fields present.
+- All five H2 sections present.
+- Requirements has ≥ 1 bullet.
+- Verification has either commands or the pure-design escape phrase.
+
+Substantive (ideate's job during elicitation):
+- Each Requirement is independently verifiable.
+- Each Constraint has a reasoning clause.
+- Out of Scope explicitly enumerates non-goals.
+- Verification commands actually verify the Requirement they map to (no "looks plausible" verification).
+- Spec text is plain language — no jargon walls, no "for future flexibility" hedging.