@laitszkin/apollo-toolkit 3.8.4 → 3.9.0

package/CHANGELOG.md

@@ -34,6 +34,11 @@ All notable changes to this repository are documented in this file.
 ### Added
 - (None yet)
 
+## [v3.9.0] - 2026-05-05
+
+### Changed
+- Refine agent-facing descriptions and workflow copy across planning, review, and submission skills (`commit-and-push`, `version-release`, `generate-spec`, `implement-specs*`, `develop-new-features`, `enhance-existing-features`, `review-spec-related-changes`, `solve-issues-found-during-review`, `maintain-skill-catalog`, `align-project-documents`, `maintain-project-constraints`); keep CI-visible contract wording aligned with `test/skill-workflows.test.js`.
+
 ## [v3.8.4] - 2026-05-04
 
 ### Changed

package/align-project-documents/SKILL.md

@@ -1,158 +1,86 @@
 ---
 name: align-project-documents
-description: Read the entire codebase, then generate standardized project documentation under docs/features/, docs/architecture/, and docs/principles/ from code evidence. Remove old documentation that does not conform to the template structure, then refresh AGENTS.md/CLAUDE.md via maintain-project-constraints.
+description: >-
+  Regenerate standardized tree `docs/features` (BDD zero code paths), `docs/architecture` (macro layer rules), `docs/principles` (evidence-backed conventions) after reading the ENTIRE production codebase—legacy scattered Markdown must migrate or be removed before finish then invoke **`maintain-project-constraints`** so AGENTS/CLAUDE indexes match disk.
+  Use for repo-wide doc realignments (“rebuild project docs from code”)—skip for single-file README nitpicks unless user explicitly requests full regeneration.
+  Violation examples: features mentioning `src/foo.ts`… acceptable feature: “Given signed-in user When export Then CSV downloads”… architecture stays stable if module renamed internally…
 ---
 
 # Align Project Documents
 
 ## Dependencies
 
-- Required: `maintain-project-constraints` to refresh `AGENTS.md/CLAUDE.md` after documentation changes.
+- Required: `maintain-project-constraints` after `docs/` work to refresh `AGENTS.md`/`CLAUDE.md` and the doc index.
 - Conditional: none.
 - Optional: none.
-- Fallback: not applicable.
+- Fallback: If `maintain-project-constraints` cannot run, **MUST NOT** pretend the constraints files are refreshed—report the gap.
 
-## Standards
+## Non-negotiables
 
-- Evidence: Treat source code, configuration, scripts, and tests as the sole source of truth.
-- Execution: Read the entire codebase before writing any documentation; ground every claim in concrete file paths.
-- Quality: Remove outdated documentation that does not conform to the template structure; never leave mixed documentation formats in place.
-- Output: Produce standardized, maintainable documentation organized into three categories: features, architecture, and principles.
+- **MUST** read the **entire** codebase (all meaningful source/config/test entrypoints—not a single-folder sample) **before** writing category docs; code is sole truth—existing prose is corroborating only.
+- **MUST NOT** ship `docs/features/` bullets that cite file paths, function names, or implementation detail—user-facing **BDD** only (`Given` / `When` / `Then`).
+- **`docs/architecture/`** stays **macro** (layers, boundaries, data-flow direction)—**MUST NOT** document code that will rot on every refactor.
+- **`docs/principles/`** **MUST** remain traceable to **concrete** repo patterns (with examples)—not aspirational platitudes without evidence.
+- **MUST** create or refresh `docs/features/`, `docs/architecture/`, `docs/principles/` with categorized files; **MUST** remove or migrate stale non-conforming docs (**MUST NOT** leave mixed legacy layout alongside new structure indefinitely).
+- **MUST** invoke **`maintain-project-constraints`** after category docs stabilize so `AGENTS.md`/`CLAUDE.md` indexes match disk.
+- Default doc **language**: match user preference or repo’s dominant README/docs language consistently per run.
 
-## Goal
+## Standards (summary)
 
-Generate a complete, code-grounded project documentation set under `docs/` that describes what the system does from a user perspective (features), how it is designed (architecture), and what conventions govern its code (principles).
+- **Evidence**: Paths and reads logged while building claims; contradictory old docs flagged, not blindly merged.
+- **Execution**: Whole repo read → ingest old docs → write three pillars → prune → constraints refresh.
+- **Quality**: Features user-only; architecture stable abstractions; principles evidence-backed.
+- **Output**: Standardized tree + synced agent constraint files.
 
-## Target Documentation Structure
+## Target structure
 
 ```
 docs/
-├── features/       — BDD-described user-facing capabilities, categorized by functional area
-├── architecture/   — macro-level design principles, organized by module or layer
-└── principles/     — code style, naming conventions, dependency management, and development constraints
+├── features/       — User-facing capability, BDD only (no code paths)
+├── architecture/   — Layers/modules, boundaries, integration contracts (macro)
+└── principles/     — Style, tooling, conventions with codebase examples
 ```
 
-### docs/features/
-
-- Describe what the system does from a user's perspective.
-- Never reference specific code paths, file names, or implementation details.
-- Use BDD (Behavior-Driven Development) phrasing: "Given ... When ... Then ...".
-- Group features by functional category; each category gets its own markdown file.
-- File titles must clearly convey which functional area or module they cover.
-
-Example feature description:
-
-```markdown
-# 用戶認證與授權
-
-## 登入
-
-- **Given** 用戶擁有有效的帳號密碼
-- **When** 用戶提交登入表單
-- **Then** 系統驗證憑證並返回存取令牌，用戶進入主頁面
-```
-
-### docs/architecture/
-
-- Extract macro-level design principles from the codebase.
-- Group principles by module or architectural layer; each module gets its own markdown file.
-- Every principle must be sufficiently abstract to avoid becoming stale after minor code changes.
-- Focus on module responsibilities, boundary rules, data flow direction, and integration contracts — not on specific implementation details.
-
-Example architecture principle:
-
-```markdown
-# API 層設計原則
-
-## 路由與處理器分離
-
-路由定義與請求處理邏輯存放在不同模組中。路由層只負責 URL 映射與中介軟體綁定，
-處理器層負責請求解析、業務邏輯調用與回應組裝。
-```
-
-### docs/principles/
-
-- Extract code style, naming conventions, and development constraints from the codebase.
-- Categorize into separate markdown files (e.g., naming conventions, dependency management, error handling patterns).
-- Each principle must be traceable to concrete examples in the codebase.
-
-Example principle:
-
-```markdown
-# 命名約定
-
-## 檔案命名
-
-- TypeScript 模組檔案使用 kebab-case：`user-service.ts`
-- React 元件檔案使用 PascalCase：`UserProfile.tsx`
-- 測試檔案與被測檔案同名，加上 `.test` 後綴：`user-service.test.ts`
-```
+Extended rules and checklist: `references/templates/standardized-docs-template.md`.
 
 ## Workflow
 
-### 1) Read the entire codebase
-
-- Read every source file in the repository to build a complete mental model.
-- Pay special attention to:
-  - Entry points (CLI commands, server startup, job runners)
-  - Public-facing interfaces (API routes, CLI commands, UI pages)
-  - Module boundaries and dependency directions
-  - Configuration files, environment variables, and external service integrations
-  - Test files that document expected behavior
-- Record concrete file paths as evidence for every claim that will appear in documentation.
-
-### 2) Read existing project documentation as reference
+**Chain-of-thought:** **`Pause →`** after each major phase; ambiguity on “user-visible” vs “internal” ⇒ re-read callers before classifying.
 
-- Enumerate all existing documentation files (`README.md`, `docs/**`, `CONTRIBUTING.md`, etc.).
-- Extract factual claims that can be cross-referenced with the codebase.
-- Note gaps where documentation is missing or outdated.
-- Treat existing docs as secondary sources; code is always the primary source of truth.
+### 1) Read entire codebase
 
-### 3) Generate new documentation following the template structure
+- Cover entrypoints (CLI/server/workers), public surfaces, boundaries, configs, integrations, tests as behavior specs.
+- Keep an **evidence notebook** (paths) for principles and architecture—not for features text.
+  - **Pause →** Did I skip generated/vendor/`node_modules`/binary blobs incorrectly included as “must read”?
+  - **Pause →** Can I name the **top five** externally visible behaviors from code alone?
 
-- Create `docs/features/`, `docs/architecture/`, and `docs/principles/` directories if they do not exist.
-- For each category, classify findings from the codebase and write focused markdown files.
-- Titles must be descriptive and immediately tell the reader what the file covers.
-- Write in the user's language unless the repository clearly uses a different documentation language.
+### 2) Read existing prose
 
-**Features generation checklist:**
-- Identify all user-facing capabilities from routes, CLI commands, UI pages, and job outputs.
-- Group into functional categories (e.g., authentication, data export, notifications).
-- Write BDD scenarios for each feature using Given/When/Then.
-- Each file covers one functional category.
+- List `README.md`, `docs/**`, `CONTRIBUTING.md`, etc.; extract facts that code confirms; flag obsolete sections.
+  - **Pause →** Where did I treat Markdown as authoritative over a contradicted implementation?
 
-**Architecture generation checklist:**
-- Identify major modules or layers from the codebase directory structure and import graph.
-- For each module, extract the design principles that govern its structure and boundaries.
-- Keep principles at the macro level; avoid principles that would need updating for minor code changes.
-- Each file covers one module or architectural layer.
+### 3) Generate three pillars
 
-**Principles generation checklist:**
-- Identify recurring patterns in code style, naming, error handling, dependency management, and testing.
-- Categorize patterns into separate files (e.g., `coding-style.md`, `naming-conventions.md`, `dependency-management.md`).
-- Support each principle with a brief rationale traceable to the codebase.
+- **features/**: categories → one markdown per category → BDD scenarios only.
+- **architecture/**: one file per layer/module cluster → boundaries and flows, stable wording.
+- **principles/**: split files (`naming-conventions.md`, etc.) → each point ties to observable repo habit.
+  - **Pause →** Random feature paragraph: grep for `./src` or `` ` `` — if found, rewrite for user observable outcome only.
 
-### 4) Remove old documentation that does not conform
+### 4) Remove non-conforming legacy
 
-- Scan `docs/` and the repository root for documentation files that do not fit the new structure.
-- Remove any documentation file whose content has been fully migrated into the new structure.
-- Keep only files that belong to the new structure or have not yet been migrated.
-- When in doubt, preserve the file and note it as a candidate for later migration.
+- Delete or migrate files fully superseded; if uncertain, **keep** file list in report as migration backlog — **do not** silently duplicate two competing truths forever.
 
-### 5) Update AGENTS.md/CLAUDE.md via maintain-project-constraints
+### 5) Refresh constraints
 
-- After the new documentation is complete, invoke `maintain-project-constraints` to refresh `AGENTS.md/CLAUDE.md`.
-- `maintain-project-constraints` will read the codebase (or the newly generated docs), extract macro business goals, write them to `AGENTS.md`/`CLAUDE.md`, and maintain the project document index.
+- Run **`maintain-project-constraints`** so Commands / Business Goals / Doc Index mirror new files.
 
-## Quality Gate (must pass before finishing)
+### 6) Gates before finish
 
-- Every feature description is written from a user perspective with no code references.
-- Every architecture principle is macro-level and resilient to minor code changes.
-- Every code principle is traceable to concrete examples in the codebase.
-- All generated files have descriptive, scannable titles.
-- No stale documentation remains that duplicates or contradicts the new structure.
-- `maintain-project-constraints` has been run and `AGENTS.md`/`CLAUDE.md` is up to date.
+- No code paths in features; architecture still macro after imagined small refactor; principles cite real examples; index lists every file under the three dirs; constraints skill executed.
 
-## Reference Template
+## Sample hints
 
-- `references/templates/standardized-docs-template.md`: describes the three-category documentation structure, writing rules, and quality checklist for each category.
+- **Feature OK**: “Given a signed-in user When they export Then a CSV download starts” — no `handlers/export.rs` references.
+- **Feature bad**: “Call `ExportService.run` …” — violates Non-negotiables (implementation leak).
+- **Architecture OK**: “API layer handles I/O only; domain module owns business rules” — stable across internal renames.
+- **Principle OK**: “TypeScript files use kebab-case — see `src/user-profile/`” — traceable pattern.

package/commit-and-push/SKILL.md

@@ -1,94 +1,71 @@
 ---
 name: commit-and-push
-description: "Guide the agent to submit local changes with commit and push only (no versioning). Use when users ask to commit, submit, or push changes without requesting tag/version/release operations. Depend directly on `archive-specs` when completed plan sets should become durable docs or when project docs need alignment, and let that skill own the downstream documentation synchronization work."
+description: >-
+  Commit and push only (no semver): inspect staged vs unstaged, classify scopes, run mandated reviews (`review-change-set`, conditional `discover-edge-cases`/`harden-app-security`), **`submission-readiness-check`** BEFORE final commit honoring `CHANGELOG.md` Unreleased + `archive-specs` redirections, preserve intentional staging splits, forbid UI git stubs, VERIFY remote hashes post-push **`version-release` elsewhere**.
+  Use for “please commit”, “submit”, “push branch” lacking explicit semver/tag language **STOP** tagging here… BAD skip readiness red… GOOD staged subset untouched unrelated dirty files changelog mirrors diff… hashes `git rev-parse HEAD` versus upstream… archive specs before commit flagged…
 ---
 
 # Commit and Push
 
 ## Dependencies
 
-- Required: `submission-readiness-check` before the final commit.
-- Conditional: `archive-specs` when completed plan sets should be converted or repository docs need alignment; `review-change-set` is required for code-affecting changes; `discover-edge-cases` and `harden-app-security` are important review gates that remain conditional, but become required whenever the reviewed scope or risk profile warrants them.
+- Required: **`submission-readiness-check`** immediately before the **final** commit.
+- Conditional: **`archive-specs`** when readiness (or completed specs) requires doc conversion or categorized `docs/` alignment; **`review-change-set`** for every **code-affecting** scope; **`discover-edge-cases`** and **`harden-app-security`** become **required** when classification/risk indicates (same scope)—treat as blocking, not polish.
 - Optional: none.
-- Fallback: If any required dependency is unavailable, stop and report the missing dependency.
+- Fallback: Any **required** dependency unavailable ⇒ **MUST** stop and report—**MUST NOT** “light” commit.
 
-## Standards
+## Non-negotiables
 
-- Evidence: Inspect git state and classify the change set before deciding which quality gates apply, then compare the actual pending diff against root `CHANGELOG.md` `Unreleased` before committing, while also distinguishing the staged surface from additional unstaged work before deciding commit scope.
-- Execution: Run the required quality-gate skills when applicable, and treat every conditional gate whose scenario is met as blocking before submission; hand the repository to `submission-readiness-check` for readiness classification, invoke `archive-specs` directly whenever completed plan sets should be converted or project docs need alignment, preserve staging intent, honor any explicit user-specified target branch, and when the worktree is already clean inspect local `HEAD`, upstream state, and the most recent relevant commit before deciding the request is a no-op; when worktree-based delivery is involved, verify where the authoritative target branch lives before moving history, re-validate on that target branch after replay or merge, and remove the temporary worktree only after the target branch is safely updated; when the user asks for multiple commits or a narrower staged subset, keep those commit boundaries explicit instead of broadening scope implicitly; then commit and push without release steps; run dependent git mutations sequentially and verify the remote branch actually contains the new local `HEAD` before reporting success, and never treat UI directives such as `::git-stage`, `::git-commit`, or `::git-push` as substitutes for actual git commands or as evidence that submission already happened.
-- Quality: Re-run relevant validation for runtime changes, preserve unrelated local work safely when branch switching or post-push local sync is required, do not bypass blocking readiness findings such as missing/stale `Unreleased` bullets or unsynchronized project docs, and never collapse intentionally separated commit scopes just because related unstaged changes are present.
-- Output: Produce a concise Conventional Commit, push it to the intended branch, and report any temporary stash/restore, commit-scope separation, or local branch sync that was required.
+- **MUST** use real `git` mutations (`git add`, `git commit`, `git push`, `git stash`, etc.); **MUST NOT** treat UI tokens (`::git-commit`, IDE buttons) as proof of history.
+- **MUST** run **`submission-readiness-check`** before final commit; unresolved readiness (e.g. stale/missing `CHANGELOG.md` **Unreleased**, doc drift) **blocks** commit.
+- Code-affecting: **`review-change-set` MANDATORY**; unresolved confirmed findings **block**. When risk profile matches, **`discover-edge-cases`** / **`harden-app-security`** equally blocking.
+- **`archive-specs`**: when readiness says convert/archive or `docs/` mismatch—**MUST** run **before** final commit, not as a vague follow-up.
+- **MUST** reconcile **staged vs unstaged** with user intent—**MUST NOT** broaden scope by auto-staging unrelated files when user staged a subset.
+- **`CHANGELOG.md` `Unreleased`**: for code-affecting or user-visible docs, **MUST** reflect this change before commit; reopen diff after edits to match commit scope.
+- **MUST** resolve **target branch** per user (or current if explicit) before rewriting history; protect unrelated dirty work (`stash` etc.); **no** force-push unless user explicitly requests.
+- After **push**, **MUST** verify remote tip matches local `HEAD` (`git rev-parse` / `@{u}` / `ls-remote`) before claiming success.
+- **MUST NOT** run version bump, tag, or GitHub release (**use `version-release`**).
+- Clean worktree requests: **MUST** inspect `HEAD`, upstream, last commit—**MUST NOT** fabricate “pushed” when already satisfied or impossible.
 
-## References
+**Repository regression checks (verbatim requirements):** Treat root `CHANGELOG.md` `Unreleased` coverage as mandatory for code-affecting or user-visible changes. Re-open the final `CHANGELOG.md` diff after readiness updates. **`review-change-set` is required for code-affecting changes**; Run `review-change-set` for every code-affecting change before continuing; treat unresolved review findings as blocking. Any conditional gate whose trigger is confirmed by this classification becomes mandatory before commit. Treat every scenario-matched gate as blocking before commit. **`discover-edge-cases` and `harden-app-security` are important review gates**—when their scenario is met, treat them as blocking review gates, not optional polish.
+
+## Standards (summary)
 
-Load only when needed:
+- **Evidence**: `git status`/`diff`; classification drives gates; changelog diff matches commit.
+- **Execution**: Inspect → classify → (deps) → readiness → commit → push verify.
+- **Quality**: No gate bypass; sequential git ops; preserve intentional commit boundaries.
+- **Output**: Conventional commit message + confirmed remote + note stash/scope if any.
+
+## References
 
 - `references/commit-messages.md`
 - `references/branch-naming.md`
 
 ## Workflow
 
-1. Inspect current state
-   - Run `git status -sb`, `git diff --stat`, and `git diff --cached --stat`.
-   - Check staged files with `git diff --cached --name-only`.
-   - Compare the staged and unstaged surfaces explicitly so you can tell whether the user already prepared a narrower commit than the full worktree diff.
-   - Inventory repository planning artifacts and project docs, not only staged files, to detect repo specs and non-standard documentation layouts.
-   - If the worktree is already clean, inspect `git log -1 --stat`, local `HEAD`, and the configured upstream state before concluding there is nothing to submit; use that evidence to determine whether the requested work was already committed and pushed, committed but not pushed, or never landed.
-2. Classify changes
-   - `code-affecting`: runtime code, tests, build scripts, CI logic, or behavior-changing config.
-   - `docs-only`: content updates only (for example README, docs, comments).
-   - `repo-specs-present`: the repository contains live project planning artifacts such as `spec.md`, `tasks.md`, `checklist.md`, or plan directories; exclude reference examples, templates, and archived samples.
-   - `repo-specs-ready-for-conversion`: the relevant `spec.md`, `tasks.md`, and `checklist.md` have been updated to reflect the actual outcome of the work, and any unchecked task/decision checkbox that is clearly not selected, replaced, deferred, or `N/A` (for example, E2E intentionally not created) does not by itself mean the spec set is unfinished.
-   - `project-doc-structure-mismatch`: existing `README.md` and project docs do not match the categorized structure required by `archive-specs`.
-   - Treat a spec set as still active when it documents remaining implementation gaps, follow-up integration work, undecided design work, or deferred tasks that still belong to the same in-flight change.
-   - Any conditional gate whose trigger is confirmed by this classification becomes mandatory before commit, including review, spec archival, docs synchronization, and changelog updates.
-3. Resolve branch target before mutating history
-   - Treat an explicit user-specified destination such as `main`, `origin/main`, or another named branch as authoritative over the current branch.
-   - If the current branch does not match the requested destination, inspect `git status --short` for unrelated local changes before switching branches.
-   - Preserve unrelated uncommitted work safely before branch operations, for example with `git stash push`, and restore it after the target branch has been updated.
-   - If the fix was committed on the wrong branch, move it to the requested branch with safe history-preserving operations such as `cherry-pick`, `merge --ff-only`, or a clean replay; do not force-push unless the user explicitly asks for it.
-   - If the user asks to sync the local target branch after pushing, fast-forward or pull that branch locally and then restore any preserved worktree changes.
-   - If the implementation lives in a detached or temporary `git worktree`, inspect both the temporary worktree and the main worktree before deciding the replay method.
-   - When the main worktree already contains staged or partially overlapping copies of the same changes, compare file content and branch tips first; do not create an unnecessary merge commit when a direct replay onto the authoritative target branch is safer.
-   - When the worktree diff is broader than the requested issue, stop and separate the requested commit scope before replaying anything to the target branch.
-4. Run code-affecting dependency skills (when applicable)
-   - Run `review-change-set` for every code-affecting change before continuing; treat unresolved review findings as blocking.
-   - Run `discover-edge-cases` and `harden-app-security` for the same code-affecting scope when the reviewed risk profile or repository context says their coverage is needed; treat them as blocking review gates, not optional polish, whenever that condition is met.
-   - Consolidate and resolve all confirmed findings before continuing.
-   - Re-run relevant tests when runtime logic changes.
-5. Run shared submission readiness
-   - Execute `$submission-readiness-check` after code/doc scans are complete and before the final commit.
-   - Let it decide whether completed plan sets should be converted, whether project docs need alignment through `archive-specs`, and whether `CHANGELOG.md` is blocking submission.
-   - Do not continue to commit while `submission-readiness-check` reports unresolved readiness blockers.
-   - Treat root `CHANGELOG.md` `Unreleased` coverage as mandatory for code-affecting or user-visible changes: if the current work is not reflected there yet, update it before committing instead of merely noting the gap.
-   - Re-open the final `CHANGELOG.md` diff after readiness updates and confirm the `Unreleased` bullets describe the same scope as the commit you are about to create.
-   - When readiness indicates doc conversion or project-doc drift, run `archive-specs` before the final commit instead of duplicating documentation alignment work locally.
-6. Commit
-   - Preserve user staging intent where possible.
-   - If the user explicitly asks for separate commits, or the staged set is already a deliberate subset of the worktree, keep those scopes separated and do not auto-stage the remaining diff unless the user expands the requested scope.
-   - If the user later broadens the requested scope, restate the new grouping, verify it against the actual staged/unstaged surfaces, and only then create the additional commit(s).
-   - Use actual `git add` / `git commit` operations; do not emit UI git directives as a stand-in for repository mutations.
-   - Write a concise Conventional Commit message using `references/commit-messages.md`.
-7. Push
-   - Push commit(s) to the intended branch.
-   - Do not overlap `git commit`, `git push`, branch switching, or post-push sync operations; wait for each mutation to finish before starting the next one.
-   - After pushing, verify the remote branch tip matches the local `HEAD`, for example by comparing `git rev-parse HEAD` with the target branch hash from `git rev-parse @{u}` or `git ls-remote --heads <remote> <branch>`.
-   - If the push result is ambiguous, out of order, or the hashes do not match, rerun the missing git step sequentially and re-check before reporting success.
-   - Confirm the local branch state matches the user's requested destination when post-push synchronization was requested.
-   - When the user explicitly asks to merge work back from a temporary worktree and delete that worktree, do the final verification on the authoritative target branch first, then remove the temporary worktree and prune stale worktree records before reporting completion.
-   - Do not claim success based on emitted UI directives or optimistic status text alone; remote-hash verification is the required evidence.
-
-## Notes
-
-- Never run version bump, tag creation, or changelog release steps in this skill.
-- Treat every scenario-matched gate as blocking before commit, not as an optional reminder to maybe do later.
-- Never skip `review-change-set` for code-affecting changes, and do not continue past review while confirmed findings remain unresolved.
-- Never downgrade `discover-edge-cases` or `harden-app-security` to optional follow-up when the change risk says they apply.
-- Never claim the repository is ready to commit while root `CHANGELOG.md` `Unreleased` is missing the current change or still describes superseded work.
-- Never fabricate a commit/push result when the worktree is already clean; either identify the exact existing commit/upstream state that satisfies the user's request or say that no matching new submission exists.
-- Never treat `::git-stage`, `::git-commit`, `::git-push`, or similar UI helpers as proof that repository history was mutated; rely on actual git command results plus local/remote hash checks.
-- Never delete a temporary worktree before the target branch has been updated, tested, and verified to contain the intended final content.
-- Never auto-stage or auto-merge unrelated unstaged changes into a commit when the user or current index state already defines narrower commit boundaries.
-- If release/version/tag work is requested, use `version-release` instead.
-- If a new branch is required, follow `references/branch-naming.md`.
-- A pushed implementation can still leave an active spec set behind; commit completion and spec archival are separate decisions.
+**Chain-of-thought:** **`Pause →`** guards skipping a gate or mis-sizing scope.
+
+1. **Inspect** — `git status -sb`; `git diff --stat`; `git diff --cached --stat`; `git diff --cached --name-only`. If clean: `git log -1 --stat`, upstream tracking, whether work already pushed.
+   - **Pause →** Is the user’s intended commit **exactly** the staged set, or full worktree—I must not mix them silently?
+
+2. **Classify** — Tag mentally: `code-affecting` | `docs-only` | `repo-specs-present` | `repo-specs-ready-for-conversion` | `project-doc-structure-mismatch` (per `archive-specs` needs). Active specs with unfinished same-change work stay active.
+   - **Pause →** Which conditional skills just became **mandatory**—did I list them explicitly?
+
+3. **Branch target** — Honor user branch; if switch needed, protect unrelated changes; cherry-pick/replay off wrong branch safely; worktree cases: identify authoritative target **before** replay.
+   - **Pause →** Am I about to merge noise because diff > issue scope—should I stop and narrow first?
+
+4. **Code-affecting gates** — `review-change-set` always; add `discover-edge-cases` / `harden-app-security` when risk/trigger says so; fix or document blockers; re-test material logic.
+
+5. **Readiness** — Run **`submission-readiness-check`**; if it routes to **`archive-specs`**, run that **now**; fix `Unreleased` bullets; recheck changelog vs staged intent.
+   - **Pause →** Could I commit while readiness still red—**why not**?
+
+6. **Commit** — Respect staging; separate commits if user asked; Conventional message per `references/commit-messages.md`.
+
+7. **Push** — Sequential; verify remote hash; sync local branch after if user asked; worktree cleanup **only after** target branch verified good.
+   - **Pause →** What two hashes prove remote == local?
+
+## Sample hints
+
+- **Scope**: Staged `foo.ts` only; unstaged `bar.ts` unrelated → commit **must not** pick up `bar.ts` without user scope change.
+- **Changelog**: Code change with no `Unreleased` bullet → **blocking** until added.
+- **Push proof**: “Pushed” means e.g. local `abc123` equals `origin/feature` `abc123`, not “command sent.”

package/develop-new-features/SKILL.md

@@ -1,134 +1,74 @@
 ---
 name: develop-new-features
 description: >-
-  Spec-first feature development workflow for new behavior and greenfield
-  features. Depends on `generate-spec` for shared planning artifacts and
-  `test-case-strategy` for risk-driven test selection before coding, then
-  implements the approved feature with focused validation.
-  Use when users ask to design or implement new features, change product
-  behavior, request a planning-first process, or ask for a greenfield feature.
-  Once the approved spec set exists and implementation begins, complete all
-  planned tasks and applicable checklist items before yielding unless the user
-  changes scope or an external blocker prevents safe completion.
-  Tests must not stop at happy-path validation: for business-logic changes
-  require property-based testing unless explicitly `N/A` with reason, design
-  adversarial/regression/authorization/idempotency/concurrency coverage where
-  relevant, use mocks for external services in logic chains, and verify
-  meaningful business outcomes rather than smoke-only success.
+  Net-new or materially new product behavior: **`generate-spec`** is mandatory (clarify → approve → only then code) with **`test-case-strategy`** backing every serious logic change—property tests required unless documented `N/A`, add adversarial/auth/idempotency/concurrency/mocks for external services, cap each spec at three modules and split coordinated batches via `coordination.md`, finish every approved `tasks.md`/`checklist.md` item or document deferrals.
+  Use when users ask for “new feature”, “greenfield slice”, “plan-first delivery”. Reroute typo-only UI, bug restores, or internal refactors without product impact to **`enhance-existing-features`** / **`systematic-debug`**.
+  Bad: editing `src/api.ts` before approval exists… Good: spec records risk → tests map to requirement IDs… Typo fix in footer copy → wrong skill…
 ---
 
 # Develop New Features
 
 ## Dependencies
 
-- Required: `generate-spec` for `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md`, clarification handling, approval gating, and completion-status backfill; `test-case-strategy` for risk-driven test selection, meaningful oracle design, and unit drift checks.
+- Required: `generate-spec` for shared planning artifacts and `test-case-strategy` for risk-driven test selection, oracles, and unit drift checks before coding.
 - Conditional: none.
 - Optional: none.
-- Fallback: If `generate-spec` or `test-case-strategy` is unavailable, stop and report the missing dependency.
+- Fallback: **`generate-spec`** **or** **`test-case-strategy`** missing ⇒ **stop** (no improvised planning/tests).
 
-## Standards
+## Non-negotiables
 
-- Evidence: Review authoritative docs and the existing codebase before planning or implementation.
-- Execution: Use specs only for feature work that is genuinely multi-step, cross-surface, or higher risk; skip specs for obviously small/localized work and route that work to direct implementation or the appropriate maintenance skill instead.
-- Quality: Use `test-case-strategy` to add risk-based tests with property-based, regression, integration, E2E, adversarial, and rollback coverage when relevant.
-- Output: Keep the approved planning artifacts and the final implementation aligned with actual completion results.
+- This skill applies to **non-trivial new behavior / greenfield**. **MUST NOT** activate for: pure bug restore; style/copy-only tweaks; trivial one-pocket config/constants; internal-only refactors/no visible behavior—these routes belong to **`enhance-existing-features`**, **`systematic-debug`**, etc., **without** new specs here.
+- **When this skill applies**, **`generate-spec` is mandatory** before product code: create/update plans, BDD reqs, contracts, design, optional batch **`coordination.md`**, obtain **explicit approval**, then implement.
+- **≤3 modules** per spec set; wider work ⇒ multiple **independent** spec sets under batch + **`coordination.md`** (no hidden cross-deps).
+- **MUST NOT** modify product code **before** approval.
+- Post-approval: **all** in-scope **`tasks.md`/`checklist.md`** items complete unless deferral/blocker documented in artifacts.
+- **`test-case-strategy`**: risk-first; property-based logic **required** unless documented **`N/A`**; adversarial/auth/idempotency/concurrency where relevant; mocks for externals in logic chains; oracles tied to requirements.
+- Backfill all plan files + coordination when batch; no fake-completed template branches.
 
-## Goal
+## Standards (summary)
 
-Use a shared spec-generation workflow for non-trivial new feature work, then implement the approved behavior with strong test coverage and minimal rework.
+- **Evidence**: Official docs + repo architecture pass before plan lock.
+- **Execution**: Route-out trivial work → spec → implement → test → backfill.
+- **Quality**: Plans trace to tests; minimal speculative code.
+- **Output**: Approved scope shipped + honest plan status.
 
 ## Workflow
 
-### 1) Review authoritative docs first
-
-- Identify the stack, libraries, APIs, and external dependencies involved.
-- Use official documentation as the source of truth.
-- Prefer Context7 for framework/library APIs; use web for the latest official docs when needed.
-- Record only the references required for this feature.
-
-### 2) Run `$generate-spec`
-
-- First decide whether the request truly belongs in this skill.
-- Do not use this skill or generate specs when the request is actually one of these:
-  - bug fixes or regressions that restore intended behavior without introducing new product behavior
-  - copy-only, styling-only, spacing-only, layout-only, or other purely presentational UI tweaks with localized impact
-  - simple configuration, constant, feature-flag, dependency, or content updates confined to one small area
-  - small refactors, naming cleanups, or internal code-health work with no externally visible behavior change
-  - narrowly scoped adjustments that touch only a few files/modules and do not require cross-team alignment or approval artifacts
-- In those cases, do not create planning docs; instead use the appropriate direct implementation workflow (for example `enhance-existing-features` for small brownfield adjustments or `systematic-debug` for bug fixes).
-- Specs are required when the request is truly a non-trivial new feature, product behavior change, or greenfield project that needs shared planning.
-- Treat each spec set as a narrowly scoped workstream that covers at most three modules.
-- If the requested change would require edits across more than three modules, do not force it into one oversized spec set.
-- Instead, split the work into multiple independent spec sets, each covering no more than three modules.
-- Define those spec sets so they do not conflict with each other and do not depend on another spec set being implemented first in order to be valid.
-- When multiple spec sets belong to one coordinated feature batch, place them under `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/` and create one shared `coordination.md` at the batch root for shared preparation, ownership boundaries, replacement direction, and merge order.
-- Follow `$generate-spec` completely for:
-  - generating `docs/plans/{YYYY-MM-DD}/{change_name}/...` for single-spec work, or `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/...` plus `coordination.md` for parallel batches
-  - filling BDD requirements and risk-driven test plans
-  - documenting external dependency contracts in `contract.md` when they materially constrain the feature
-  - documenting the architecture/design delta in `design.md`
-  - documenting shared preparation and implementation direction in `coordination.md` when multiple spec sets will be implemented in parallel
-  - handling clarification responses
-  - obtaining explicit approval before coding
-  - backfilling document status after implementation and testing, including requirement completion in `spec.md`
-- Do not modify product code before the approved spec set exists.
-
-### 3) Explore architecture and reuse opportunities
-
-- Trace entrypoints, module boundaries, data flow, and integration points relevant to the new behavior.
-- Identify reusable components, patterns, and configuration paths before adding new code.
-- Keep a concise map of likely files to modify so implementation stays scoped.
-
-### 4) Implement after approval
-
-- Reuse existing patterns and abstractions when possible.
-- Keep changes focused and avoid speculative scope expansion.
-- Update environment examples only when new inputs are actually required.
-- Once approval is granted and implementation starts, treat every unchecked in-scope item in `tasks.md` and every applicable item in `checklist.md` as required work for this run.
-- Do not stop after a partial implementation, partial test pass, or partial doc backfill when work remains in the approved plan.
-- Only pause before completion if:
-  - the user changes scope or explicitly asks to stop
-  - a new clarification invalidates the approved plan and requires renewed approval
-  - an external blocker (missing credentials, unavailable dependency, access restriction, broken upstream system) prevents safe completion
-- When blocked, record the exact unfinished items and blocker in the plan artifacts before yielding.
-
-### 5) Testing coverage (required)
-
-Use `$test-case-strategy` for every non-trivial change.
-
-- Start from risk inventory and requirement IDs, not from the happy path.
-- Define test oracles before implementation and map them to `spec.md`, `tasks.md`, and `checklist.md`.
-- For each atomic task that changes non-trivial local logic, define a focused unit drift check or record the smallest replacement verification with a concrete `N/A` reason.
-- Add unit, regression, property-based, integration, E2E, adversarial, mock/fake, rollback, or no-partial-write coverage only when the risk profile warrants it.
-- Each planned test must have a meaningful oracle: exact business output, persisted state, emitted side effects, or intentional lack of side effects.
-- Run relevant tests when possible and fix failures.
-
-### 6) Completion updates
-
-- Backfill `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md` through `$generate-spec` workflow after implementation and testing.
-- If the feature used a parallel batch, also backfill `coordination.md` with any final shared preparation, cutover, or ownership changes that emerged during execution.
-- In `spec.md`, mark each approved requirement with its actual completion state, such as completed, partially completed, deferred, or not implemented, plus brief evidence or rationale where needed.
-- Mark every completed task in `tasks.md`.
-- In `checklist.md`, update only the items that are actually applicable to the approved scope and executed validation.
-- In `contract.md`, keep the final external dependency contract records aligned with the implementation and verified upstream constraints.
-- In `design.md`, keep the final architecture/design description aligned with the implementation that actually shipped.
-- Do not mark template alternatives, unused example rows, or non-applicable decision branches as completed just to make the file look fully checked.
-- Rewrite, remove, or leave `N/A` on template-only sections so the final checklist reflects the real work rather than the starter template.
-- Explicitly label any truly remaining applicable item as deferred or blocked with the reason.
-- Report the implemented scope, test execution, and any concrete `N/A` reasons.
-
-## Working Rules
-
-- By default, write planning docs in the user's language.
-- Keep implementation traceable to approved requirement IDs and planned risks.
-- Keep each spec set limited to at most three modules; split larger changes into independent, non-conflicting, non-dependent spec sets before approval.
-- When multiple spec sets are used for one feature batch, keep cross-spec rules in `coordination.md` rather than repeating them in every `design.md`.
-- Prefer realism over rigid templates: add or remove test coverage only when the risk profile justifies it.
-- Every planned test should justify a distinct risk; remove shallow duplicates that only prove the code "still runs".
-- Treat starter template alternatives as mutually exclusive options, not as boxes that all need to be checked.
-- If a spec set exists and approval has been granted, do not yield with unfinished in-scope tasks or checklist items unless the user approves a deferment or an external blocker makes completion impossible.
+**Chain-of-thought:** If request is maintenance-sized, **`Pause →`** “Should I reroute?” before spending tokens on **`generate-spec`**.
+
+### 1) Docs & routing
+
+- Stack/deps discovery; verify using official sources.
+  - **Pause →** Is this truly greenfield/feature vs fix/polish—if latter, bail to other skill?
+
+### 2) `generate-spec`
+
+- Full workflow: dirs `docs/plans/{YYYY-MM-DD}/…`, batch/coord flags, clarification, **`MUST`** approval before code.
+  - **Pause →** Did I secretly start coding “just the types”—**hard violation**?
+
+### 3) Architecture map
+
+- Reuse seams; list likely files **after** approval to stay honest to plan.
+
+### 4) Implement (post-approval)
+
+- Execute tasks/checklist exhaustively unless blocker recorded with user-visible deferrals.
+
+### 5) Testing
+
+- **`test-case-strategy`** mapping requirement IDs ↔ tests; drift checks/`N/A` discipline; run and fix reds.
+
+### 6) Completion
+
+- Backfill **`generate-spec`**-style across **`spec/tasks/checklist/contract/design`** (+ **`coordination.md`**); requirement-level status in **`spec.md`**; strip template illusions; final report with scope + tests + `N/A`.
+
+## Sample hints
+
+- **Wrong skill**: “Fix typo in footer string” ⇒ not here.
+- **Right skill**: “Add export-to-CSV for dashboard” ⇒ **`generate-spec`** then code + property tests on CSV invariants maybe.
+- **Split**: Touches CLI + server + terraform module boundaries—three modules cap ⇒ **two spec dirs** coordinated.
 
 ## References
 
-- `$generate-spec`: shared planning and approval workflow.
-- `$test-case-strategy`: shared test selection, oracle design, and unit drift-check workflow.
+- **`generate-spec`**: planning/backfill authority
+- **`test-case-strategy`**: breadth/depth of tests