shape-project

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Shape Project

## Core Invariants

- Work under `docs/rolling-wave/{project}/`.
- Store project-level state in `project.md`; store slices in `slices/NNN-slug.md`.
- Use slice statuses: `pending`, `ready`, `in progress`, `ready for review`, `in review`, `done`.
- Multiple slices may be `ready`, `in progress`, `ready for review`, or `in review` concurrently. Each workflow invocation operates on one explicitly resolved slice.
- Accept user preferences by default, but push back when strong evidence conflicts with the workflow, prior decisions, terminology, or constraints.
- Pushback format: "I disagree because... The likely consequence is... Continue anyway?"
- Do not modify product code. This skill only creates or updates rolling-wave planning artifacts.
- Shape the whole project, not the first slice. `shape-project` defines the global finish line, success criteria, non-goals, constraints, risks, and broad roadmap across all slices.
- Slices are concrete implementation steps, not general project phases. Each slice should produce a reviewable change toward the finish line.
- Slices are delivery sequence and implementation-detail containers. Do not use "later slice" as a way to avoid deciding whether something belongs in the project finish line.
- Keep executable slices within one bounded human review decision. A slice may contain multiple independently executable or revertible chunks when one architectural intent or transformation recipe, risk class, and verification strategy cover them. Commit count, file count, domain count, and raw diff size are signals, not limits.
- A slice may be backed by another rolling-wave project when that slice is large enough to need its own finish line, roadmap, and review loop. Treat that as a parent/child planning relationship, not as de-scoping from the parent project.
- Project and slice artifacts are agent state, not human-facing documentation. Prefer stable headings, terse `key: value` bullets, IDs, and tables over explanatory prose.
- Keep skill mechanics out of project artifacts. Rules like "planning only in this phase", "do not modify product code", "ask one question at a time", or "write under docs/rolling-wave" are workflow instructions for the agent, not project constraints, non-goals, assumptions, risks, or decisions.
- Optimize for enough shared direction to prepare the next slice, not for a perfect project document.

## Interaction Rules

- Ask one question at a time only when user input is required to avoid a material planning mistake.
- Prefer bounded choices when selecting among clear alternatives.
- Use open prose questions when the answer should reveal context, evidence, or uncertainty.
- Do not ask questions already answered by existing artifacts.
- When you ask the user a shaping question, stop and wait for the answer. Do not answer it yourself and continue in the same turn unless the user explicitly asked you to make the call.
- When proposing low-risk assumptions, label them and proceed; do not force a confirmation turn just to make the artifact cleaner.
- Do not one-shot risky broad roadmaps. For straightforward projects, recommend one sequence and record uncertainty instead of presenting multiple options.
- Do not use `Open Questions` as a substitute for decisions that affect the finish line, first slice, public behavior, irreversible migration, or major cost/risk. Safe deferrals may be recorded without asking first.
- If exactly one high-impact project-shape blocker remains, ask it before finalizing. If it is low or medium impact, record it as an assumption or deferred question.
- Create or update `project.md` once the project is ready enough, unless the user explicitly asks to discuss before writing or the remaining uncertainty is high impact.

## Workflow

0. Assess shaping depth and subject clarity.
   - If the requested project subject is too vague for another agent to identify, ask what project to shape before doing anything else.
   - Classify the shaping need as `lightweight`, `standard`, or `deep`.
   - Lightweight shaping may produce a compact provisional `project.md` with minimal questioning.
   - Standard shaping should ask only for high-impact blockers and otherwise proceed on labeled assumptions.
   - Deep shaping should pressure-test direction before creating roadmap slices.
   - Shape at full ambition within the named project, but do not widen into adjacent projects unless the current project cannot be coherent without them.

1. Resolve the project.
   - If the user names a project, use that slug or create it if missing.
   - If exactly one project exists under `docs/rolling-wave/`, use it.
   - If multiple projects exist and none was named, ask which one to use.
   - Before creating a new project, normalize the requested slug and compare it with existing project folders. Push back if it strongly overlaps.

2. Inspect existing context.
   - Read existing `project.md`, slice files, nearby planning docs, and any user-provided requirements.
   - Auto-resolve answers from artifacts before asking the user.
   - Treat explicit user requirements, named docs, and existing `project.md` decisions as constraints.
   - Treat nearby docs, old slice notes, and inferred repo context as background unless the user names them as constraints.
   - Do not treat this skill's own workflow rules as project context. They govern the current shaping session only.
   - If `project.md` already exists, shape as an update: preserve prior decisions unless the user explicitly changes them, keep completed slice history intact, and move stale assumptions only when artifact evidence supports the change.
   - If context is thin, do not ask unlimited questions, but still meet the ready-enough shaping gate before writing: finish line, observable success criteria, scope boundaries, likely first implementation slices, and any product/API/policy decision that would materially change the first slice or final outcome.
   - Label remaining assumptions clearly only when they are low-impact, evidence-backed, or explicitly safe to defer to slice preparation.

3. Grill project-level direction until the project is ready enough.
   Ask one high-leverage question at a time. Cover:
   - finish line
   - success criteria
   - non-goals
   - constraints
   - assumptions
   - broad implementation slice sequence
   - dependencies
   - project-level risks
   - expected learnings

   Keep scope and sequencing separate:
   - First decide whether a requirement, behavior, risk, or non-goal belongs in the overall project shape.
   - Only after project scope is clear should the roadmap decide which slice handles it.
   - Do not ask whether a project-level requirement should be "deferred to a later slice." Ask whether it is in scope for the project at all, then record likely sequencing separately.
   - If something is too risky for the first slice but still part of the desired outcome, keep it in the project finish line or roadmap and sequence it later. Do not turn sequencing into accidental de-scoping.

   Keep slices implementation-shaped:
   - A slice is a concrete step that `prepare-next-slice` can turn into an implementation contract and `implement-slice` can build.
   - Prefer the largest batch that still fits one bounded review decision and moves the project forward without mixing risk classes.
   - Keep code, types, config, migration, docs, and other tightly coupled changes together when a reviewer needs their combined context to judge the outcome.
   - Group chunks by reviewer question and verification method. A mechanical relocation batch may cross domains when one transformation recipe applies, behavior stays unchanged, each moved unit includes consumers and existing tests, and rename-aware review separates moves from edits.
   - Split a proposed slice when chunks need separate product or architecture approval decisions, unrelated mental models, distinct risk classes, incompatible intermediate states, or materially different verification strategies.
   - Do not split merely because chunks are independently useful, executable, revertible, or could be accepted as separate commits.
   - Do not split merely to satisfy commit, file-count, or diff-size targets. Avoid temporary glue, fake sequencing, and review fragmentation.
   - Use roughly 500 non-move changed lines as a soft default review budget. Lower it for high-semantic or high-risk work; allow larger repetitive mechanical diffs when one proof covers the batch.
   - Parallel chunks divide execution ownership and review navigation inside one review decision. Prefer one to three chunks.
   - Plan broad test coverage as a final testing/validation slice after the implementation slices have settled. Earlier slices may record test backlog, probes, or verification intent, but should not require full test implementation.
   - If a concrete slice grows large enough to have its own global finish line, success criteria, and internal sequence, keep it as one parent slice and create or reference a child rolling-wave project under `docs/rolling-wave/{child-project}/`.
   - Do not expand a child project's internal slices into the parent roadmap unless the parent genuinely needs to track those steps separately.
   - Record the parent slice's completion condition in parent terms, for example "child project reaches its finish line and exports the migration notes needed by the parent project."
   - Do not create slices that are only project phases, research phases, planning phases, validation phases, or vague lifecycle stages.
   - Avoid slice names like "Design the approach", "Validate compatibility", "Phase 1", or "Future hardening" unless they are rewritten as concrete implementation deliverables.
   - Good slice framing names the product/code behavior that will change, for example "Add entitlement-aware catalog inputs" or "Filter list_items from the builtin catalog when item read is unavailable".
   - Research, design, validation, and compatibility checks belong inside the relevant implementation slice as readiness, verification, risks, or acceptance criteria unless they produce a standalone reviewable artifact needed by implementation.

   Scan for these gaps and probe only the gaps that are actually present:
   - Finish-line gap: completion is described as activity rather than an observable end state.
   - Success gap: success criteria are vague, subjective, or generic.
   - Scope-boundary gap: likely adjacent work is not explicitly included or excluded.
   - Dependency gap: the roadmap assumes unresolved inputs, tools, access, or decisions.
   - Sequencing gap: early slices do not reduce uncertainty or do not produce reviewable implementation progress.
   - Risk gap: cross-slice risks are likely but not recorded.
   - Learning gap: early slices do not identify what they should teach later slices.
   - Open-question gap: the artifact would contain a project-level question that has not actually been asked.

   If useful, derive 3-5 project axes such as user workflow, data shape, migration risk, rollout, docs, or reliability. Use them only to check question coverage, not to create a detailed upfront plan.

   Classify unresolved questions before writing:
   - Ask-now questions materially affect the finish line, success criteria, scope, non-goals, first slice, public/user-facing behavior, compatibility policy, rollout policy, irreversible migration, or major project-level risk.
   - Safe deferrals are implementation details for a future slice, low-impact unknowns, facts that slice preparation can verify from code, or items the user explicitly chooses to defer.
   - Ask-now questions cannot be silently moved into `Open Questions`. Ask them one at a time, or record an explicit user deferral.

4. Shape and grill the broad implementation slices.
   This is not `prepare-next-slice`; do not fully specify each slice. The goal is shared understanding of the broad delivery sequence.

   Before writing roadmap rows:
   - Recommend one broad slice sequence by default.
   - Propose 2-3 plausible slice sequences only when ordering materially changes risk, cost, reversibility, or what the first slice can teach.

From rijkvanzanten/rolling-wave-engineering, MIT.

More from rijkvanzanten/rolling-wave-engineering