planning
Turn a description of a feature, product or system into a PRD at .gener8v/prd.md (3-7 capability areas, user scenarios, scope boundaries, open questions) and open a change brief under .gener8v/changes/ with its priority cut. Use when the user describes something new they want built, such as 'I want to build a support portal' or 'add a feature that lets agents export results': a greenfield product, new scope on a project already on the pipeline (Planning opens a new change for it rather than folding it into a change in delivery), or the first feature after brownfield onboarding. Not for onboarding an existing codebase with no PRD (brownfield) or detailing an area the current change already covers (specification).
- License 许可
- MIT
- 最近更新
- 2026-10-22
- Stars
- ★ 3
- Forks
- 0
01 前言 Front Matter
- name
- planning
- description
- Turn a description of a feature, product or system into a PRD at .gener8v/prd.md (3-7 capability areas, user scenarios, scope boundaries, open questions) and open a change brief under .gener8v/changes/ with its priority cut. Use when the user describes something new they want built, such as 'I want to build a support portal' or 'add a feature that lets agents export results': a greenfield product, new scope on a project already on the pipeline (Planning opens a new change for it rather than folding it into a change in delivery), or the first feature after brownfield onboarding. Not for onboarding an existing codebase with no PRD (brownfield) or detailing an area the current change already covers (specification).
- argument-hint
- [what you want built]
02 资源文件 25
- 资产文件assets/change-brief.md956 B
- 资产文件assets/prd.md1.6 KB
- 参考文档catalog.json1.3 KB
- 参考文档references/api.md5.1 KB
- 参考文档references/contracts.md3.1 KB
- 参考文档references/cred-scoring.md2.6 KB
- 参考文档references/example.md6.4 KB
- 参考文档references/siwa.md4.1 KB
- 脚本scripts/check-cred.sh235 B
- 脚本scripts/helixa-agent.sh208 B
- 脚本scripts/helixa-agents.sh153 B
- 脚本scripts/helixa-cred.sh221 B
- 脚本scripts/helixa-get.sh1.5 KB
- 脚本scripts/helixa-mint.sh452 B
- 脚本scripts/helixa-name.sh213 B
- 脚本scripts/helixa-post.sh1017 B
- 脚本scripts/helixa-search.sh334 B
- 脚本scripts/helixa-stake-info.sh91 B
- 脚本scripts/helixa-stake.sh208 B
- 脚本scripts/helixa-stats.sh86 B
- 脚本scripts/helixa-update.sh367 B
- 脚本scripts/helixa-verify.sh348 B
- 脚本scripts/mint-agent.js1.8 KB
- 参考文档SOURCE.md159 B
- 参考文档TRUST.auto.yaml2.1 KB
03 SKILL.md 正文
Planning Skill
Purpose
Transform a user prompt into a structured Product Requirements Document (PRD) that describes the functional capabilities needed to satisfy the request, and open the change that will deliver it: a change brief naming the initiative, the capability areas it touches, and the priority cut. The PRD is a living artifact, amended in place across initiatives; the brief belongs to one initiative. Both are designed for downstream decomposition by LLM agents into detailed specifications and tickets.
When to Use
Use this skill when:
- A user describes a new feature, product, or system they want built
- A user has a problem statement that needs translation into requirements
- Work needs to be scoped before technical planning begins
- A new initiative starts on a project already on the pipeline: a second change, or the first feature after Brownfield onboarding (Planning amends the PRD and opens a new change)
Input
Source: User prompt (natural language description of what they want built), including any must / should / could the user states. Ask for that cut if it is missing; the change brief's Priority Cut is filled from it. Location: Provided directly by the user in conversation. No file input is required for a first initiative.
Also read when present:
.gener8v/CONVENTIONS.md: the slug rule, vocabularies and roles.gener8v/prd.md: the living PRD to amend (never overwrite).gener8v/changes/*/change.md: existing changes, so the new slug does not collide and the new brief does not duplicate an open initiative
Output
Produces: Two markdown documents: the living PRD and a change brief Write to:
.gener8v/prd.md: the Product Requirements Document (living; amended in place, with a## Change Log).gener8v/changes/<change-slug>/change.md: the change brief for this initiative (shape inassets/change-brief.md) Creates directories:.gener8v/and.gener8v/changes/<change-slug>/if they do not exist
Change slug: kebab-case, derived from the initiative's title with the slug rule in CONVENTIONS.md §3 ("Search relevance v2" → search-relevance-v2). Choose it before writing anything: it names the directory every downstream change artifact lives in (changes/<change-slug>/tickets/, changes/<change-slug>/delivery/, changes/<change-slug>/reviews/) and never changes afterwards.
There is always a change. A greenfield first initiative writes prd.md and changes/<change-slug>/change.md; the first change is not special. Both documents are written with **Status:** Draft and **Approved by:** pending. When the Product Owner approves in conversation, update both lines on the approved document (**Status:** Approved, **Approved by:** Product Owner — <name>, YYYY-MM-DD).
If .gener8v/prd.md already exists (a second initiative, or the first change after Brownfield onboarding), Planning does not overwrite it. It reads the existing PRD, adds new capability areas or amends existing ones in place, keeps every existing area name (downstream slugs and requirement prefixes depend on them), marks anything dropped *(Withdrawn YYYY-MM-DD)*, and appends an entry to the ## Change Log section at the end of the document saying what changed and why, naming the change slug. Existing change briefs are never edited by Planning. Downstream skills then run only for the areas this change touches, under changes/<change-slug>/.
The PRD is the single entry point for all downstream skills; they reference this path to locate it. The change brief is what Specification and Ticket Breakdown read to learn which areas and requirements this initiative touches and what not to build.
System Context (Optional)
After producing the PRD, ask the user whether they want to provide system context — information about their existing technology stack, infrastructure, team capabilities, and organizational constraints. If provided, write to .gener8v/context.md as freeform markdown, including a ## Repositories table (| Directory | Purpose | Language / build | Verify commands |) with one row for a single repository and several for a workspace.
This file is not required for the pipeline to proceed, but significantly improves the quality of Constraints analysis and Technical Design. Without it, those skills infer constraints from functional documents alone.
Output Format
Produce two markdown documents, each from its template in assets/. Read the template before writing and follow it exactly, headings, field lines and table columns included: scripts/gener8v-state.py parses them.
PRD: .gener8v/prd.md
Write it in the shape of assets/prd.md. The state script takes the first # heading as the PRD title, the **Status:** line as its approval state, and each ### heading under ## Functional Capabilities as a capability area — the slug of that heading names the area's specification, constraints, technical design and ticket directories. A trailing *(Withdrawn YYYY-MM-DD)* is stripped from the name.
Change brief: .gener8v/changes/<change-slug>/change.md
Write it in the shape of assets/change-brief.md. The state script reads its **Status:** line and parses the ## Affected Capability Areas table row by row — area name, kind, requirements cell — to derive the change's areas and which of them are still pending specification; lint checks every requirement ID in a cell against that area's specification.
Planning fills every Affected Capability Areas row's Requirements cell with (pending specification); the Kind column is adds area or modifies. Specification replaces the cell with the real IDs (Adds / Modifies / Withdraws) when it runs for the change and appends its own Change Log line. The state script recommends specification <area> for <change> while a cell still says pending.
Principles
Functional Over Technical
Describe what the system should do, not how it should be implemented. Avoid mentioning specific technologies, architectures, or implementation approaches unless they are explicit constraints from the user.
Good: "The system should allow users to upload documents and extract key information automatically."
Avoid: "The system should use S3 for storage and call an LLM API to parse PDFs."
Balanced Granularity
Break work into major capability areas (typically 3-7) that are meaningful but not exhaustive. Each area should be substantial enough to warrant its own detailed specification pass, but not so broad that it obscures important distinctions.
Capture Ambiguity Explicitly
When the user prompt is vague or leaves room for interpretation, do not assume. Instead:
- Make a reasonable interpretation for the PRD
- Document the assumption in Open Questions
- Flag decisions that need stakeholder input
Scope Boundaries
Be explicit about what is out of scope. This is especially important for:
- Adjacent features that seem related but aren't requested
- Future phases or enhancements
- Integrations or dependencies not mentioned
Living PRD, Scoped Change
The PRD describes the whole product as it should be after every change so far; it is amended, never rewritten, and its capability area names are stable. The change brief describes only this initiative: which areas it adds or modifies, and the Priority Cut, which is where "what not to build" is decided. Put product truth in the PRD and initiative scope in the brief; do not repeat the PRD's capability bullets in the brief.
Process
-
Parse Intent: Read the user prompt and identify the core problem or outcome they're seeking.
-
Identify Capability Areas: What major functional areas does this work span? Group related capabilities together.
-
Draft Capabilities: For each area, enumerate what the system should do using clear, testable statements.
-
Ground in Scenarios: Write 2-4 user scenarios that demonstrate the capabilities working together.
-
Define Boundaries: Explicitly list what's out of scope to prevent future confusion.
-
Surface Unknowns: Capture any ambiguity, missing information, or decisions needed as open questions.
-
Review for Technical Leakage: Scan the document and remove any implementation-specific language.
-
Choose the Change Slug: Derive it from the initiative's title with the slug rule in
CONVENTIONS.md§3, and check.gener8v/changes/so it does not collide with an existing change. -
Write the PRD, Amending Rather Than Overwriting: Write
.gener8v/prd.mdwith**Status:** Draftand**Approved by:** pending. If a PRD already existed, confirm every pre-existing capability area is still present (or explicitly withdrawn), and record the change in## Change Logwith the change slug. -
Write the Change Brief: Write
.gener8v/changes/<change-slug>/change.mdin the shape ofassets/change-brief.md:**Status:** Draft,**Approved by:** pending, every Affected Capability Areas row at(pending specification), the Priority Cut filled from the user's stated must / should / could (ask when it is missing), and a Change Log lineopened (Planning). -
Record Approval: Ask, do not wait. Present the artifact and request approval before the session moves on to another area, another skill, or another run — an artifact left
Draftbecause nobody was asked is indistinguishable in the record from one the user declined to approve. When the user approves the PRD or the brief in conversation, set**Status:** Approvedand**Approved by:** Product Owner — <name>, YYYY-MM-DDon that document. Until then the record saysDraft, and Audit warns if downstream stages are produced from it.
Example
The worked example shows both files Planning writes for the Support Documentation Search System: the living prd.md (three capability areas, Status and Change Log lines) and the change brief changes/support-search/change.md with its Affected Capability Areas at (pending specification) and its Priority Cut. It lives at skills/planning/references/example.md. Read it before producing your first artifact of this kind.
Troubleshooting
- The chosen change slug already names a directory under
.gener8v/changes/. Choose another: the slug names every artifact directory of the change and never changes afterwards. If the existing change is the same initiative, this is not a new change — resume it (Orchestrate says where it stands) instead of opening a second brief for the same work. - The user states no must / should / could. Ask before writing the brief. The Priority Cut is the only place priority enters the pipeline — Specification tags requirements from it and every ticket's
**Priority:**comes from it — so a cut Planning invents reappears on every ticket as if the Product Owner had set it. - An existing capability area's name no longer fits. Keep the name and clarify the area in its bullets. The slug of the
###heading names the area's specification, constraints, technical design and ticket directories; renaming the heading orphans them, and the state script warnsspecifications/<old-slug>.md has no matching capability area in the PRD. A rename that cannot be avoided is recorded in the Change Log and renames every dependent file with it. - Orchestrate warns
change '<change-slug>' names area '<area-slug>' which is not in the PRD. A row in the brief's Affected Capability Areas table does not match a###heading in the PRD — the script slugifies both and compares the slugs. Correct the row's area name, or add the area to the PRD when this change introduces it. - Orchestrate warns
PRD has no '### ' capability areas under '## Functional Capabilities'. The section heading was renamed or the areas were written at another heading level. Restore the structure ofassets/prd.md; until then no area has a slug, and nothing downstream can be located.
Integration with Other Skills
This skill produces output that feeds into:
- Specification Skill: Reads the change brief, takes each affected Capability Area and amends its living specification, then replaces the brief's
(pending specification)cell with the requirement IDs it added, modified or withdrew - Constraints Skill: Analyzes the PRD for technical, compliance, or integration constraints
- Dependencies Skill: Maps dependencies between capability areas and external systems
- Technical Design Skill: Translates specifications and constraints into architecture decisions
- Ticket Breakdown Skill: Reads the brief's Priority Cut and Affected Capability Areas and decomposes the change's requirements into
changes/<change-slug>/tickets/<area-slug>/(oneTICKET-NNN.mdper ticket, plusbacklog.md) - Orchestrate Skill: Reads the PRD and lists changes (
active_changes, per-change status and pending specification / breakdown inpipeline-state.yaml) to determine pipeline status and next steps
Alternative entry point:
- Brownfield Skill: For existing codebases, the Brownfield skill produces the living baseline (the PRD and specifications) bottom-up from code instead of top-down from user intent, and opens no change. The first feature afterwards is a Planning change like any other.
Revisions
- A second initiative is a new change: re-running this skill opens
.gener8v/changes/<new-change-slug>/change.mdand amends.gener8v/prd.mdin place, recording the change in## Change Log. The PRD is never overwritten, and existing change briefs are never edited by Planning - Only the downstream artifacts of the areas the new change touches become stale; the state script recommends
specification <area> for <change>while a brief cell still says(pending specification) - If the change is limited to one capability area, re-run only the affected downstream skills for that change (Orchestrate's
warningswill flag a specification whose area was renamed or withdrawn) - If capability areas are added or removed, the Orchestrate skill can identify which downstream artifacts need to be created or are now orphaned
- A change that will not ship is not deleted: set its brief to
**Status:** Abandonedwith a Change Log line saying why - System context (
.gener8v/context.md) does not need to be regenerated when the PRD changes unless the project scope shifts significantly
Notes
- Do not include time estimates; these are determined during ticket breakdown
- Do not include acceptance criteria; these are defined during specification
- Keep the document readable by non-technical stakeholders
- The PRD should be understandable without access to the original prompt
- Do not record priorities on PRD capability bullets; the Priority Cut lives in the change brief, and per-requirement priority tags are allocated by Specification
- For existing codebases not yet on the pipeline: If the project already has working code and no
.gener8v/prd.md, use the Brownfield skill first. Brownfield works bottom-up (code → specifications → PRD) and writes the living baseline; Planning works top-down (intent → PRD → change brief → specifications) and opens every change, including the first feature after onboarding
04 同仓库更多 Skills
ticket-breakdown
Decompose one capability area's requirements for one change into implementable tickets with Priority, Value, acceptance criteria, Prior Art, Output contracts, Known Hazards, dependency ordering and relative sizing: one TICKET-NNN.md per ticket plus backlog.md, in the change's tickets directory. Use when a specification is approved and the team needs work items, such as 'break this spec into tickets' or 'create the backlog for search'. Not for implementing a ticket (delivery) or ordering whole capability areas (dependencies).
technical-design
Translate specifications, constraints and dependencies into architecture decisions (AD-XXX), component boundaries, data model and interface contracts under .gener8v/technical-design/. Use when technology or architecture choices must be settled before tickets are written, such as 'which datastore should we use' or 'design the components for search'. Skip it when the approach is obvious and uncontested. Not for judging an architecture that has already shipped (architecture-review).
specification
Expand one capability area from .gener8v/prd.md into a functional specification with atomic, testable [PREFIX]-REQ-XXX requirements, behaviors, edge cases and open questions under .gener8v/specifications/. Use when a PRD capability area needs elaboration before constraints, technical design or tickets, or a change brief still marks an area as pending specification, such as 'spec out the search area' or 'write the requirements for billing'. Not for the whole product (planning) or work items (ticket-breakdown).
setup
Bootstrap the gener8v pipeline in a project: create .gener8v/, copy the conventions, generate pipeline-state.yaml, and add the pipeline directives to CLAUDE.md. Use when the user says 'set up gener8v' or 'initialize the pipeline', when a project has no .gener8v/prd.md, or after a plugin upgrade to refresh the conventions. Not for deciding what to do next on a project already on the pipeline (orchestrate).
security-review
OWASP-informed, code-level security review of delivered code: injection, authentication and authorization, data exposure, configuration, dependencies, cryptography and logging, with attack scenarios for Medium+ findings and compliance constraints (CC-XXX) treated as Critical. Use after a delivery, especially one touching input handling, auth, sensitive data or external integrations, such as 'security review TICKET-007' or 'check what this delivery shipped for injection or auth bypass before we merge'. Not for a whole-codebase OWASP posture assessment (owasp-top10-review) or prompt-injection risk in LLM features (owasp-llm-top10-review).
rot-watch
Detect decay in code that is being actively written: measure six signals (packaging drift, dependency direction, comment language, growth slopes, tests, the detectable subset of SOLID) against a recorded baseline and report only what moved, at .gener8v/rot/. Use once code has been delivered and again every few deliveries, before a release, or when asked 'is the codebase getting worse' or 'has this module drifted'. The first run records the baseline and reports nothing. Not for one delivery's quality (quality-review), defects (defect-sweep) or whether the architecture was right (architecture-review).