# Octospec Workflow

> Use when implementing a feature, fixing a bug, or making any non-trivial code change in this repository. Drives the octospec 4-phase engineering flow (Plan, Implement, Verify, Finish) so the change follows this repo's rules in .octospec/ and ships a PR with a linked spec. Triggers on requests like "add ...", "implement ...", "fix ...", "refactor ...", "change the ... API", 写功能, 修 bug, 加接口, 改逻辑. Skip for trivial edits (typo, docs, lint, pure config) — those do not need the flow.

- Skill: `mininglamp-oss/octospec-workflow` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mininglamp-oss/octospec-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mininglamp-oss/octospec-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: mininglamp-oss (https://skillmd.com/u/mininglamp-oss)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mininglamp-oss/octospec-workflow

---


# octospec workflow

This repository uses the **octospec** engineering standard. When you are asked to
make a non-trivial code change here, run the 4-phase flow instead of editing code
directly. Rules live in `.octospec/` and are the source of truth for this repo's
conventions.

## When to run this

Run the flow for: a new feature, a bug fix, a refactor, an API change, or any
change that touches load-bearing behavior.

**Do NOT run the flow** for trivial changes: a typo, a docs-only edit, a
lint-only fix, a pure config or dependency bump. Just make those directly.

## The 4 phases

Run them in order. Each phase maps to a slash command the user can also invoke
manually; as a skill you perform the same steps.

### 1. Plan
- Choose a short kebab-case `<slug>`.
- Read `.octospec/tasks/_brief.template.md`.
- Inspect the relevant existing code, then write
  `.octospec/tasks/<slug>/brief.md` with: Goal, Load-bearing list (use the same
  tags as `.octospec/rules/_index.yaml` `inject_when.touches` where they apply),
  Out of scope, Acceptance.
- **Show the brief and get confirmation before writing code.**

### 2. Implement
- Resolve applicable rules: read `.octospec/rules/_index.yaml` and
  `.octospec/_global/` (if synced). A rule applies when its `inject_when.paths`
  glob matches a file you will touch, OR its `inject_when.touches` tag is in the
  brief's load-bearing list. A repo-tier rule overrides a global one with the
  same id.
- **Read the full text of each matching rule and follow it.** Prioritize
  `load_bearing: true` rules.
- Record what you used in `.octospec/tasks/<slug>/context.yaml`.
- Write the code. Do not commit yet.

### 3. Verify
- Review the diff against each injected rule (trace load-bearing paths, not just
  the happy path).
- Confirm the diff meets the brief's Acceptance and did not touch anything in
  Out of scope.
- Run this repo's gates (lint / type-check / tests; see CLAUDE.md / AGENTS.md).
- Self-fix what you can.

### 4. Finish
- Run the final gate once more.
- Write `.octospec/journal/shared/<slug>.md` (what was done + any learning).
  Start it with OKF frontmatter (`type: Journal` + title/description/tags/
  timestamp) and add a dated entry to `.octospec/log.md`.
- Promote any reusable learning **in this same PR**: edit the relevant
  `.octospec/rules/<rule>.md` in place (or add a new rule + `_index.yaml` entry)
  — the PR review is the gate. The helper `.octospec/scripts/octospec-update-spec.sh`
  gives you the raw material (`--kind=rule` → a draft in
  `learnings/pending/<slug>-rule-draft.md` + a promotion block on stdout;
  `--kind=task` → a per-actor journal entry). It never auto-writes `rules/`, so
  **you** copy the draft into `rules/<id>.md` and update `_index.yaml` here, in
  this PR, then drop the scratch draft — never defer it to a separate PR or a
  later move. Only use `.octospec/learnings/pending/` for *unresolved* learnings
  that still need human design before becoming a rule; finished learnings must
  not be stranded waiting on a phantom separate PR.
- Open a PR. Fill the PR template's **Linked Spec** (→ the brief) and the
  **COMPREHENSION** three questions to substance, for load-bearing /
  architectural / P0 changes.

## Notes

- This skill orchestrates the flow automatically. The user can still drive any
  single phase manually with `/octospec-plan`, `/octospec-go`, `/octospec-check`,
  `/octospec-finish`.
- The flow is guidance, not a hard gate; the repo's PR/CI checks are the
  enforcement layer.