# Implementation Cycle > Runs the repo's full implementation cycle with approval gates, analysis, delivery, and remediation. Use when the user wants to implement or change behavior in the plugin. - Skill: `phel-lang/implementation-cycle` (Agent Skill) - Install (CLI): `npx skillmds@latest add phel-lang/implementation-cycle` - Raw SKILL.md: https://api.skillmd.com/api/skills/phel-lang/implementation-cycle/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: phel-lang (https://skillmd.com/u/phel-lang) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/phel-lang/implementation-cycle --- Use this skill for requests like `implement #42` or `implement hover docs for core macros`. Inputs: a GitHub issue number, issue URL, or freeform request in `$ARGUMENTS`; the repo's workflow commands; existing feature artifacts when resuming. ## Artifact location (graceful degradation) This repo is not required to be Spec Kit-bootstrapped. Resolve the artifact home in this order: - If `.specify/` exists, use the repo's Spec Kit feature structure and templates. - Otherwise, write lightweight artifacts under `docs/specs//` (`spec.md`, `plan.md`, `tasks.md`), where `` is `short-kebab-summary`, preferably prefixed with the issue number. Whichever home is chosen, those artifacts are the source of truth; never fork into ad hoc files outside it. Rules: - Resume from the current unfinished stage if a spec, plan, tasks, findings report, or delivery notes exist; don't restart unless the user asks for a reset. - Stop at each approval gate with the exact approval phrase below, unless the user requested an autonomous run. - Route to `/workflow.document-existing` if the request is documenting/reverse-specing existing behavior; to `/workflow.debug` if it's primarily diagnosing a bug/flaky test/regression/failure. - Verify Phel language facts against `api.json` and https://phel-lang.org/, and grammar/PSI facts against the actual `.flex`/`.bnf` sources and generated code in `src/main/gen/` — never from memory. Workflow: 1. Validate environment: - The repo root has `build.gradle.kts` and `gradlew`. - `/workflow.brainstorm`, `/workflow.prepare-worktree`, `/workflow.team-run`, `/workflow.attack`, `/workflow.fix`, `/workflow.delivery`, and `/workflow.debug` exist in `.claude/commands`. 2. Classify the request: - Issue number/URL ⇒ ticket mode; otherwise ⇒ freeform mode. - If nothing meaningful is present and there are no resumable artifacts, stop and explain what is missing. - If `/workflow.classify` is available, run `/workflow.classify $ARGUMENTS` and follow its output: - `direct` (TRIVIAL/SIMPLE): skip steps 3–11. State what will change in 1–2 sentences, make the edit, run `./gradlew test` (or `build`), summarize. Do not write spec/plan/tasks artifacts unless the user asks. - `sdd` (MODERATE): continue with the full workflow from step 3 onward. - `sdd+brainstorm` (COMPLEX): continue from step 3 but run `/workflow.brainstorm ` before the spec phase. - `clarify-first` (UNCLEAR): ask the one question returned by the classifier, wait for the answer, then re-run classification. - If `/workflow.classify` is not available, continue the full cycle from step 3 (backward-compatible default). - In autonomous mode, log the classification result and continue without stopping for `clarify-first`. 3. Intake and analysis: - In ticket mode, fetch the issue via `gh issue view ` when available. - In freeform mode, restate the request as an implementation objective with explicit scope, likely constraints, and assumptions before writing artifacts. - Discover the affected surface first: Grep/Read over `src/main/kotlin/org/phellang/` (`actions/`, `annotator/`, `completion/`, `language/` + `parser/`, `inspection/`, `syntax/`), `plugin.xml`, the grammar sources, and the registry. - If the request is large, ambiguous, brownfield, high-risk, or has multiple plausible directions, run `/workflow.brainstorm `. - If the request modifies an existing capability and there is no trustworthy current-state spec yet, run `/workflow.document-existing ` first. - If the impacted surface spans 3+ files, crosses 2+ packages, or clearly requires end-to-end tracing, run `/workflow.team-run analysis ` before finalizing the spec. 4. Spec phase: - Create or update `spec.md` at the resolved artifact home. - Capture scope, non-goals, dependencies, version-compat assumptions, open questions, and known risk areas (grammar ordering, PSI contracts, generated-source impact). - If the spec already exists, update it in place rather than duplicating it. 5. Spec approval gate: - Summarize scope, major technical decisions, open questions or assumptions, and expected blast radius. - End with: `Spec ready. Reply with "approve spec" to continue or tell me what to change.` - Skip only when autonomous mode was explicitly requested. 6. Plan phase: - Create or update `plan.md`. - Make verification (`./gradlew test`/`build`), rollback, registry-regeneration, generated-source, and version-compat expectations explicit where relevant. 7. Plan approval gate: - Summarize implementation order, verification strategy, and external dependencies. - End with: `Plan ready. Reply with "approve plan" to continue or tell me what to change.` 8. Tasks phase: - Create or update `tasks.md`. - Make task ordering, dependencies, validation steps, and any parallel-safe work explicit. 9. Consistency analysis: - Cross-check spec ⇄ plan ⇄ tasks for gaps or contradictions before implementation. Apply required updates before the final pre-implementation approval. 10. Task approval gate: - Summarize task order, parallelizable work, high-risk tasks, consistency findings, and required verification. - End with: `Tasks ready. Reply with "approve tasks" to continue or tell me what to change.` 11. Worktree preparation: - Run `/workflow.prepare-worktree ` for non-trivial work, especially broad, cross-package, brownfield, grammar/PSI, or risky changes. - Preserve the current environment only when it is already an isolated workspace suitable for the task. 12. Implementation: - Implement directly, or run `/workflow.team-run implementation ` for parallel-safe task sets. - If grammar (`.flex`/`.bnf`) or the registry (`NamespaceConfig.kt`) changed, regenerate (`./gradlew generatePhelLexer generatePhelParser updatePhelRegistry`) and stage the generated output. - Register every new feature in `plugin.xml`. - If scope changes materially, update the affected artifact and re-open the relevant approval gate unless autonomous mode was requested. 13. Review and remediation: - Run `/workflow.attack`. - Run `/workflow.fix` on the resulting findings report. 14. Delivery: - Run `/workflow.delivery`. 15. Final status: - Summarize what shipped, what was verified, what remains blocked, and the exact next action if the cycle did not finish. Resume behavior: - On `approve spec`/`approve plan`/`approve tasks`/`continue`/`resume`, inspect feature artifacts and continue from the next unfinished stage. - For review, remediation, tests, or commit/PR prep, prefer `/workflow.attack`, `/workflow.fix`, or `/workflow.delivery`. - If reframed as diagnosis/flaky behavior/root-cause, prefer `/workflow.debug`; if documenting/reverse-engineering, prefer `/workflow.document-existing`. - For freeform-started features, keep the spec and plan as the source of truth instead of re-parsing the original message. Exit criteria: - Spec, plan, and task artifacts in place/updated at the resolved artifact home. - Brainstorming, clarification, and analysis used when ambiguity or risk justified them. - Approval gates respected (or bypassed only on explicit autonomous request); implementation reflects approved scope. - Generated sources and `plugin.xml` are in sync; adversarial findings reviewed and remediated. - Test status, commit status, PR summary, and remaining risk are explicit.