start-feature
Use when the user asks Pi to start a HEPHA FEAT implementation, run start-feature, or run start-implementing for a READY FEAT from a registered project workspace, for example "use the start-feature skill for FEAT-003".
- License 许可
- MIT
- 最近更新
- 2026-10-31
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- start-feature
- description
- Use when the user asks Pi to start a HEPHA FEAT implementation, run start-feature, or run start-implementing for a READY FEAT from a registered project workspace, for example "use the start-feature skill for FEAT-003".
- agent_action
- start-feature
03 SKILL.md 正文
Start Feature
Model Authority
This procedure is model-neutral. When invoked directly, execution is
direct_host and remains in the current Pi, Codex, or Claude Code session; that
active host owns model selection. Do not query Hepha routing policy, request a
model switch, automatically hand off, choose a fallback model, or fabricate
route-policy evidence. Direct execution does not fabricate an orchestrated
receipt. Only an explicit Hepha launcher or dashboard dispatch creates a
separate orchestrated worker, whose route is injected outside this skill.
You are executing the HEPHA start-implementing workflow directly from Pi.
This skill is for console-driven implementation startup and for HEPHA WebApp
workers that mount the same skill. It must work when Pi is opened from a
registered project or parent workspace and the user names the active project
plus a FEAT id such as FEAT-003.
Objective
Resolve the active HEPHA project and MemoryBank, locate the requested FEAT, perform the start-feature transition when the FEAT is still READY, then in autonomous mode continue contract-declared phases with verification, code review, required fixes, and review reruns until every declared phase is resolved or a real blocker requires human input.
Required Inputs
Accept these from the user's message:
- project name or alias, such as
HEPHA,Hepha, orAgenticDevelopmentProcess; - FEAT id, such as
FEAT-003; - optional MemoryBank path override;
- optional mode, where
autonomousmeans continue through subsequent phases without stopping after the start transition.
If the FEAT id is missing, ask one concise question. Otherwise, infer safely.
Workspace And Project Resolution
- Treat the current directory as the workspace starting point.
- Resolve the active project named by the user and locate its repository root.
- Read the project
AGENTS.mdand project brief or MemoryBank overview when present before editing. - Resolve the active project:
HEPHA,Hepha, andAgenticDevelopmentProcessmap to<workspace root>/AgenticDevelopmentProcess.- If the user names another project, use
docs/projects.mdor the nearest child repo folder matching that name.
- Read the child project
AGENTS.mdandREADME.mdwhen present. - Run project git, build, test, and edit commands from the child project root, not from the parent workspace.
MemoryBank And FEAT Resolution
Resolve the MemoryBank in this order:
- User-supplied MemoryBank path, if present.
.hepha/projects.jsonin the child project, matching projectname,id, or child root path.<child project root>/MemoryBankwhen it containsFeatures/.- A direct search under the child root for
MemoryBank/Features.
Then resolve the FEAT:
- Normalize the requested FEAT id to uppercase, for example
FEAT-003. - Search these folders under
<MemoryBank>/Features:02_READY_TO_DEVELOPfirst;03_IN_PROGRESSsecond, for HEPHA WebApp runs that already performed the folder move or direct runs that are being resumed;- then
01_SUBMITTED,04_COMPLETED, and05_CANCELLEDonly for diagnostics.
- Match a FEAT folder by folder name or by
FeatureDescription.mdcontent. - Continue only when the FEAT is in
02_READY_TO_DEVELOPor03_IN_PROGRESS. - Require
FeatureDescription.md,FeatureTasks.md,PhaseExecutionContract.json, and every contract-declared phase document. - Stop if the FEAT contains
[NEEDS VALIDATION], and report exact file and line references.
Start Transition
When the FEAT is in 02_READY_TO_DEVELOP:
- Inspect
git status --short --branchfrom the project root. - Stop before changing branches if unrelated dirty files make the transition unsafe.
- Create or switch to branch
feat/<FEAT-folder-name>unless HEPHA-provided runtime context names a different target branch. - Move the FEAT folder to
Features/03_IN_PROGRESS, preserving the folder name and files. - Update
FeatureDescription.mdandFeatureTasks.mdso status and folder references say the FEAT is in progress. - Update linked EPIC references when the parent EPIC is available.
- Create or update
start-feature-report.mdin the FEAT folder with branch, source folder, target folder, timestamp, and validation findings.
When the FEAT is already in 03_IN_PROGRESS, do not move it back to READY.
Repair stale READY/SUBMITTED references in FEAT documents, ensure a
start-feature-report.md exists, then continue from the first unresolved
contract phase.
Create focused checkpoint commits at meaningful gates when safe, especially for
the start transition and review-approved phase gates. Never push during this
skill; complete-feature handles pushes, merges, and completed-folder moves
after human gates are accepted.
Start-Feature Post-Operation: Estimates
Before any implementation phase begins, calculate and write the following for every contract-declared phase:
Estimated Human Time: focused engineering time for a competent developer;Estimated AI Time: active agent/runtime time, excluding waiting and human checkpoints.
Use only parseable compact values: 30m, 1h, or a same-unit range such as
2-3h. In ranges, use the literal ASCII hyphen-minus (-, U+002D) only; never
use an en dash (–, U+2013), em dash (—, U+2014), or another typographic dash.
Before returning, inspect every phase estimate and the ## Implementation Timing Summary; replace any typographic range dash with the ASCII hyphen-minus. Add
## Implementation Timing Summary to FeatureTasks.md, with full-FEAT totals
for both estimates. Do not invent actual duration: HEPHA records it from completed
phase worker start/end timestamps. Stop and report a blocker if any contract-declared
phase lacks both parseable estimates or the timing summary before implementation starts.
Phase Resolution
Build the phase inventory before editing. PhaseExecutionContract.json is the
only source of phase topology and ordering; never infer it from a phase number,
title, or filename:
- Read
FeatureTasks.md. - Read and validate
PhaseExecutionContract.json, then read exactly its declared documents. - Parse phase status from the
FeatureTasks.mdcontract inventory first, then from a phase file status line such as**Status:** COMPLETED. - Normalize statuses:
Completed,Complete->COMPLETEDSkipped,N/A->SKIPPEDNot Started,NOT_STARTED,Pending->PENDINGIn Progress->IN_PROGRESSCheckpoint In Progress->CHECKPOINT_IN_PROGRESSCode Review In Progress->CODE_REVIEW_IN_PROGRESSAwaiting Review->AWAITING_REVIEWAwaiting User Acceptance->AWAITING_USER_ACCEPTANCEBlocked,Failed,Rejected->BLOCKED
- Stop with a blocker if the execution contract is missing, invalid, or its
declared documents do not match the
Phases/directory. - The current phase is the first contract-ordered phase that is not
COMPLETEDorSKIPPED, unless a review-finding report clearly requires returning to a specific earlier phase. - If every contract phase is
COMPLETEDorSKIPPED, scan each phase's## Quality Gate Evidencetable. If any gate decision ismissing, treat the first contract-ordered phase with a missing gate as the current phase for quality-gate repair only.
Autonomous Phase Loop
When the user says autonomous, continue through phases in execution-contract order:
- Start at the current unresolved phase.
- Complete or skip only that phase's scoped work.
- Update durable task evidence and narrative notes in the phase document. Hepha owns lifecycle/status fields and FeatureTasks status cells.
- Run focused verification.
- Run code review when needCodeReview is true.
- Fix blocking review findings, rerun focused verification, and rerun code review.
- Record completion or skip evidence only after verification and review gates are clear; Hepha deterministically writes the lifecycle state.
- Rescan phases from disk.
- Continue to the next unresolved contract phase.
Stop only when:
- all declared contract phases are
COMPLETEDorSKIPPED; - all phase quality gates are
satisfied,waived, ornot applicable; - a real blocker requires human judgment;
- credentials, permissions, missing dependency, or unsafe action prevents safe progress;
- the same failure repeats after a documented recovery attempt;
- the user requested interactive mode and the start transition is complete.
Per-Phase Work Rules
Before changing code in a phase:
- Read the phase document.
- Read
planning-analysis-report.mdwhenever the current contract phase's planning-index row identifies it as required context. - Read relevant parent EPIC and FEAT acceptance criteria, including linked
EpicAcceptanceTests.mdscenarios and the current phase'sEPIC Acceptance Traceabilityassignments inFeatureTasks.mdwhen present. - Read applicable
MemoryBank/LessonsLearneddocuments. - Inspect current git status from the child project root.
- Preserve existing checked Markdown checklist items.
- For a V3 phase,
PhaseExecutionContract.jsonis the machine task authority. The## Phase Task Ledgermust be its exact checkbox projection: one entry per contract task, same order, matching[contract:<id>]and[executor:<executor>]markers. Never add an uncontracted checkbox there. Put descriptive work under## Detailed Workas plain bullets. - If the phase has no checkbox ledger, add a compact
## Phase Task Ledgerfrom its declared contract tasks before substantive work.
During implementation:
- Work only the current phase scope.
- Skip checked tasks unless a changed file, failed verification, or review finding explicitly invalidates them.
- Do not edit reserved machine fields:
**Status:**, FeatureTasks Status cells, or Quality Gate Evidence Decision cells. Hepha writes them from durable workflow events. - Record task progress and evidence; Hepha applies the lifecycle transition.
- Do not broaden scope to dashboard/UI/sync behavior unless the phase explicitly requires it.
- Do not move the FEAT folder out of
03_IN_PROGRESS. - Do not start dev servers, watch commands, or long-running UI processes.
- Do not push to remotes.
- Do not revert unrelated user changes.
Verification Rules
Apply the serialized-build-commands skill when available before running build,
test, lint, format, Cargo, pnpm, npm, or other shared-state commands.
Run one verification command at a time. Wait for the result, inspect it, then decide the next command.
Prefer focused phase verification first. Run broad verification only when the phase or final checkpoint requires it and the narrower checks are green.
Do not invent test results. Record exact commands and observed outcomes in the phase evidence.
The phase declarations are authoritative: needCodeReview and needTestCoverage are independent booleans; all four combinations are valid. Ordered native tasks and explicit configured checks retain their own obligations. Phase identifiers, positions, titles and file types never select gates. Developers can revise declarations with before/after values, implemented scope, reason and evidence, without hiding failures. Reuse valid evidence for unchanged inputs. Ordinary missing tests or rejected reviews remain same-phase repair work; escalate only a concrete impasse or repeated lack of a meaningful repair path.
Phase Quality Gate Evidence
Agents write evidence in phase documents. Hepha owns the machine-readable
lifecycle fields (**Status:** and FeatureTasks Status) and Quality Gate
Decision cells. Do not alter those reserved fields. New phase documents created
by RefineFeature use this table:
| Gate | Decision | Evidence / Justification |
|---|---|---|
| Changed files | missing | Exact production, test, and documentation paths changed in this phase. |
| Tests | missing | Exact test files and commands, or a waiver explaining why tests are not useful for this phase. |
| Gherkin/Playwright E2E | not applicable | Required only at the explicitly assigned workflow execution owner; retain EPIC E2E updates and execution links alongside phase TwinTests. |
| Code review | missing | Phase review report path, or an explicit waiver and risk rationale. |
Rules:
- Follow the declared coverage and review flags with scope reasons for N/A. Execute independently required checks even when both flags are false.
- UI changes may require frontend TwinTests and EPIC E2E updates. Run full-workflow E2E at its declared owner; a passing TwinTest never waives it.
- Do not claim a phase is complete with a required
missinggate. Supply the missing evidence or justification and let Hepha retain the lifecycle state. - Do not mark a phase complete while an EPIC acceptance scenario assigned to that phase lacks its planned executable evidence or an exact documented existing-coverage mapping.
Quality-Gate Repair Mode
When all implementation phase work is already completed but one or more phase
quality gates are missing, do not redo completed implementation tasks. Work
only the missing gates:
- Missing
Code review: inspect the declared review obligation and existing report. When required, repair findings and obtain approval for the applicable scope. If scope changed, record a justified declaration revision; do not infer review applicability from file types or directly overwrite machine-owned decision cells. - Missing
Tests: inspect the declared acceptance coverage and required commands. Reuse valid execution and assertion evidence, repair missing meaningful coverage, and execute missing or invalidated required checks. A justified declaration revision must preserve actual failures and the remaining obligations. - Missing
Gherkin/Playwright E2E: inspect the assigned workflow obligation and original execution evidence. Repair and execute that obligation at its declared owner; isolated tests cannot replace a required full-workflow check. - Preserve completed phase implementation task checkboxes. Do not broaden scope beyond the missing gate unless a review finding requires a fix.
Code Review Rules
For every code-relevant phase:
- Prefer a dedicated subagent Code Review Agent when a Pi subagent facility is
available, including
pi-subagents,@gotgenes/pi-subagents, or an Agent tool exposed by the active Pi profile. - Give the reviewer the FEAT id, current phase, changed files from git status/diff, relevant phase docs, acceptance criteria, and exact verification output. Do not ask the reviewer to re-run implementation.
- If no subagent facility is available, perform a separate review pass in the current Pi session and record that fallback in the report.
- Write each review report under
<FEAT folder>/code-reviews/with a phase-specific name such asphase-2-code-review-<timestamp>.md. - Treat BLOCKER, REQUIRED, and
NEEDS_CHANGESfindings as mandatory. - For every finding, create or update a decision ledger recording fixed, deferred, accepted-risk, rebutted, follow-up, or blocked with evidence.
- After fixing any blocking finding, rerun the smallest relevant verification and rerun code review before advancing.
- Continue the fix-and-review loop until the latest report is APPROVED or has no blocking findings, or until the same issue repeats after a documented recovery attempt.
Do not mark a phase complete while blocking review findings remain. Notes and polish items must be explicitly resolved as fixed, deferred, accepted-risk, rebutted, or follow-up.
Output Contract
At the end of the run, report:
- project root and MemoryBank path used;
- FEAT id and folder;
- branch used;
- whether the start transition was performed or already done;
- phases completed/skipped during this run;
- code-review reports created and rerun status;
- verification commands and results;
- blocker, if any;
- changed files.
Keep the final summary concise and concrete.
04 同仓库更多 Skills
serialized-build-commands
Agents should invoke this skill before running build, test, lint, or format commands that use shared caches, file locks, build directories, or package manager state. Use especially before Rust Cargo commands such as cargo check, cargo test, cargo clippy, cargo fmt, cargo build, or any shell command containing cargo.
submit-epic
Use when the user asks Pi to submit, create, or draft a new HEPHA EPIC directly from a registered project workspace, preserving the useful legacy DevCycle MCP submit-epic command, for example "submit-epic for HEPHA build observability projection hooks" or "create a HEPHA EPIC titled Runtime Approval Gates".
refine-feature
Use when the user asks Pi to run refine-feature, refine a HEPHA FEAT, create FeatureTasks and phase files, or move a clarified FEAT to Ready To Develop, for example "refine-feature FEAT-004" or "Use the refine-feature skill for HEPHA FEAT-004".
design-feature
Use when the user asks Pi to run design-feature, design a HEPHA FEAT, create UI requirements, or prepare UX/design artifacts for a FEAT, for example "design-feature FEAT-004" or "Use the design-feature skill for HEPHA FEAT-004".
deep-dive
Use when the user asks Pi to run a HEPHA Deep-Dive for an EPIC or FEAT, gather Deep-Dive questions, or apply saved Deep-Dive answers to a MemoryBank document, for example "use the deep-dive skill for HEPHA FEAT-004".
continue-implementation
Use when the user asks Pi to continue implementation, continue-implementing, resume implementation, or run a HEPHA FEAT implementation such as "use the skill continue implementation for FEAT-002" from a registered project workspace.