@laitszkin/apollo-toolkit 3.8.4 → 3.9.0

package/implement-specs-with-worktree/SKILL.md

@@ -1,134 +1,85 @@
 ---
 name: implement-specs-with-worktree
 description: >-
-  Read a specs planning set (spec.md, tasks.md, checklist.md, contract.md, design.md)
-  from `docs/plans/{YYYY-MM-DD}/{change_name}/` or `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/`
-  plus parent `coordination.md` and `preparation.md` when present, and implement
-  the approved tasks within an isolated git worktree, with every code, test, and
-  spec edit made inside that worktree rather than the parent checkout. Use when the user asks
-  to implement from an existing spec set, execute a spec plan, or work on a
-  feature branch without affecting the parent working tree. If not already in a
-  worktree, create a new worktree with a spec-named branch from the same parent
-  branch as the worktree base, implement all planned tasks, then commit the
-  changes to that local branch when complete.
+  Same contract as **`implement-specs`** but every write happens inside a dedicated `git worktree` + feature branch; verify `pwd` equals `git rev-parse --show-toplevel` before touching code; parent checkout remains read-only for deliverables; honor `preparation.md` baselines and sibling collision rules from `coordination.md`.
+  Pick when the user or batch workflow demands isolation (“don’t disturb my dirty main”, per-spec worker). Plain same-branch edits stay on **`implement-specs`** instead.
+  Good: commands show matching paths after `git worktree add ../oauth-scope feat/oauth-scope`. Bad: patching files under the primary checkout tree for implementation output.
 ---
 
 # Implement Specs with Worktree
 
 ## Dependencies
 
-- Required: `implement-specs`, `enhance-existing-features`, and `develop-new-features` for implementation standards.
+- Required: `implement-specs` for the shared discovery / implementation / backfill / commit / reporting lifecycle; `enhance-existing-features` and `develop-new-features` for implementation standards.
 - Conditional: `generate-spec` if spec files need clarification or updates.
-- Fallback: If `implement-specs`, `enhance-existing-features`, or `develop-new-features` is unavailable, stop and report the missing dependency.
+- Fallback: If any required dependency skill is unavailable, **MUST** stop and report it.
 
-## Standards
+## Non-negotiables
 
-- Evidence: Read and understand the complete specs set before starting implementation, including parent `coordination.md` and `preparation.md` when present, identify the authoritative parent branch that the worktree should inherit from, verify whether the requested scope is already implemented on that parent branch or current main working tree, and when the requested plan path is missing from the current worktree verify where the authoritative copy actually lives before substituting any nearby spec.
-- Execution: Create or use an isolated worktree for implementation only when the requested spec still needs work, sync the exact approved plan set into that worktree when it is missing there, create the worktree branch from the same parent branch as the worktree base, use the spec-set name as the canonical branch/worktree name, inspect sibling worktrees for the same batch before editing shared files when parallel implementations may already be active, prefer direct `git` ref checks over brittle shell inference when deciding whether a branch or worktree already exists, and commit to a local branch when done. Do not edit product files from the parent checkout; every implementation, test, and spec backfill change must happen inside the active worktree directory after verifying `git rev-parse --show-toplevel` and `pwd` point at the same worktree root.
-- Quality: Complete all planned tasks, run relevant tests, backfill the spec documents with actual completion status, avoid dragging unrelated sibling specs into the worktree just because they share a batch directory, inspect overlapping runtime/config/shared touch points before diverging from another active sibling worktree in the same batch, revert unrelated formatter-only noise outside the spec-owned scope before committing, if branch/worktree creation reports ambiguous state re-check the actual git refs and worktree list before retrying, and when using targeted Rust `cargo test` selectors remember Cargo accepts only one positional test filter so each distinct selector needs its own confirmed command.
-- Output: Keep the worktree branch clean with only the intended implementation commits.
+- **MUST** perform every write (product code, tests, and spec-document backfill) inside the active worktree: after each `cd`, **MUST** confirm `pwd` equals `git rev-parse --show-toplevel` for that worktree before editing.
+- **MUST NOT** edit implementation files from the parent checkout except for creating or listing worktrees and read-only inspection; the parent checkout is write-prohibited for this spec’s deliverables.
+- **MUST** follow the **`implement-specs` Workflow** for discovery, implementation, backfill, commit discipline, and completion reporting—**except** that branch/worktree restrictions in `implement-specs` Non-negotiables are replaced by this skill’s worktree rules.
+- **MUST** create the implementation branch from the **same parent branch** the user/session identified as the baseline (often the branch that will receive the merge—not necessarily `main` unless that branch is verified as the base).
+- **MUST** use the spec directory name (`change_name`) as the canonical basename for the worktree path and branch stem; branch **`type`/name** must follow `references/branch-naming.md`.
+- **MUST** use `git show-ref` and `git worktree list --porcelain` (not shell guesses) when checking whether a branch or worktree already exists; if creation fails ambiguously, **MUST** re-query those commands before retrying.
+- When `preparation.md` exists: **MUST** treat it as an already-committed shared baseline for parallel work; **MUST NOT** redo its tasks inside the member spec unless the preparation commit is missing or the document states the prerequisite is still blocked. If baseline assumptions break, **MUST** update `preparation.md` or stop for coordination—**MUST NOT** silently move prerequisite work into the member spec.
+- **MUST** complete the same quality bar as `implement-specs`: all in-scope tasks, relevant tests, honest backfill, no sibling-spec scope creep, revert formatter-only noise outside owned files before commit.
+- **MUST NOT** `git push` unless the user explicitly asks.
+- For targeted Rust tests: **MUST** pass at most one positional `cargo test` filter per invocation; use separate commands or a broader confirmed filter when multiple selectors are needed.
 
-## Goal
+## Standards (summary)
 
-Implement approved spec planning sets in an isolated git worktree, ensuring the parent working tree is never interrupted by in-progress work.
+- **Evidence**: Read full spec set plus `coordination.md` and `preparation.md` when present; verify whether the spec is already implemented on the baseline before opening a new worktree; if the plan is missing in the worktree, sync the authoritative copy and re-read before coding.
+- **Execution**: Isolated worktree only; branch naming per `references/branch-naming.md`; check sibling worktrees before editing shared boundaries in a parallel batch.
+- **Quality**: Same as `implement-specs`, plus collision awareness with sibling worktrees per `coordination.md`.
+- **Output**: Clean local branch in the worktree with intended commits only; parent working tree unchanged by this implementation.
 
 ## Workflow
 
-### 1) Identify and read the specs set
+**Chain-of-thought:** Answer each **`Pause →`** question before leaving the phase; if any answer conflicts with Non-negotiables, fix state first (right directory, right root, right baseline).
 
-Use $implement-specs for the standard spec discovery and reading workflow.
+### A) Specs and baseline
 
-Additionally:
+- Run **`implement-specs` Workflow steps 1–2** in spirit: resolve paths, read all core files and `coordination.md`; run `git status` / `git worktree list` as needed. If the plan files are absent in the target worktree, sync them in, then re-read in that tree.
+- Read `preparation.md` when present; apply the Non-negotiable baseline rule above.
+  - **Pause →** Where will authoritative plan text live **for this session**—parent tree, worktree after sync—and have I opened that copy end-to-end?
+  - **Pause →** Does `coordination.md` / `preparation.md` imply **anything** I must not redo or must assume stable before coding?
 
-- When `preparation.md` exists in the parent batch directory, treat it as the already-completed prerequisite baseline for this spec; do not redo its tasks inside the member spec unless the preparation commit is missing or the document says the prerequisite remains blocked.
+### B) Worktree and branch
 
-### 2) Check current worktree state
+- If the requested scope is already implemented and verified on the baseline, **MUST** report `no-op` with evidence instead of creating duplicate work.
+- Otherwise: ensure the shell is in the correct worktree (create one if required):
+  - Derive `change_name`; branch pattern `<type>/<spec-name>` per `references/branch-naming.md`; worktree directory `../<spec-name>` (or an equivalent path the user approves).
+  - `git branch <branch-name> <parent-branch>` then `git worktree add <path> <branch-name>`; `cd` into it; verify `pwd` vs `git rev-parse --show-toplevel`.
+- Before editing shared modules in a batch, check `git worktree list --porcelain` and `coordination.md` for sibling ownership; read sibling diffs when the same file is touched.
+  - **Pause →** Why is **`parent-branch`** definitely the correct baseline—not an unexamined assumption that `main` is default?
+  - **Pause →** Could this work duplicate an **already-merged** implementation; what **evidence** (`git log`, tests, code search) did I use to rule that in or out?
+  - **Pause →** After `cd`, do `pwd` and `git rev-parse --show-toplevel` **match**; if not, why am I not stopping before any write?
+  - **Pause →** Which sibling worktree might already own the shared file I am about to touch, and did I inspect their diff?
 
-- Run `git worktree list` to see existing worktrees and branches.
-- Determine if the current session is already inside a worktree (check `git rev-parse --show-toplevel` and compare with `git worktree list`).
-- If the current worktree is missing the exact requested plan set, sync that plan into the worktree before coding and re-read the synced files there so implementation happens against the same plan snapshot that will be backfilled later.
-- Before making any edits, confirm the active shell is inside the intended worktree directory; if not, stop editing, create or enter the required worktree first, and only then continue.
-- Determine the authoritative parent branch for the new worktree:
-  - if the current checkout already comes from a branch, reuse that branch as the base
-  - if the current session is inside a detached worktree, identify the parent branch that owns that worktree before creating another branch from it
-  - do not default to `main` unless `main` is actually the parent branch of the worktree you are extending
-- Before creating a new worktree, inspect the parent branch and current main working tree for evidence that the requested spec is already implemented:
-  - search the codebase, tests, and recent git history for the exact feature boundary or cutover named by the spec
-  - if the requested plan is archived, treat that as a signal to verify whether the implementation already landed before starting any new branch
-  - when the requested behavior is already present and verified, report a `no-op` result with concrete evidence instead of recreating the same work in a fresh worktree
-- When the spec belongs to a parallel batch and other local worktrees for sibling specs already exist, inspect those sibling worktrees before editing any shared boundary module (for example shared runtime, config, or contract files):
-  - use `git worktree list --porcelain` plus the batch ownership map in `coordination.md` to identify likely sibling worktrees
-  - if a sibling worktree already touches the same shared file, read that diff first and either stay within your owned additive boundary or update the coordination evidence before proceeding
-  - do not assume coordination is collision-free just because the plan scopes differ at the directory level
+### C) Implement, backfill, commit, report
 
-### 3) Create a new worktree if needed
+- Execute **`implement-specs` Workflow steps 3–6** (implement, backfill, commit, report) **entirely from the worktree root**, applying `enhance-existing-features` / `develop-new-features` standards.
+- In the report, **MUST** include branch name, worktree path, commit hash, tests run, backfilled docs, and an explicit statement that the parent checkout was not modified for implementation files.
+  - **Pause →** Am I honoring **implement-specs** step 3–6 **constraints** literally while respecting that all writes happen **only** under this worktree root?
+  - **Pause →** If I used Rust `cargo test` filters, did I violate the **single positional filter** rule; how would I split the commands?
 
-If not already in a worktree, or if the user explicitly requests a fresh worktree, and the spec is not already implemented:
+## Sample hints
 
-- Derive the canonical spec name from the requested `change_name` directory.
-- Use that spec name as the shared branch/worktree identifier:
-  - branch name: `<type>/<spec-name>` following `references/branch-naming.md`
-  - worktree directory name: `<spec-name>`
-- Create a new branch for this implementation from the same parent branch identified in step 2:
+- **Root check** (must print the same path twice before edits):
   ```bash
-  git branch <branch-name> <parent-branch>
+  pwd && git rev-parse --show-toplevel
   ```
-- Add a new worktree:
+- **Skeleton commands** (`change_name` `oauth-scope`, parent `feature/x`, type `feat`):
   ```bash
-  git worktree add ../<spec-name> <branch-name>
+  git branch feat/oauth-scope feature/x
+  git worktree add ../oauth-scope feat/oauth-scope
+  cd ../oauth-scope
   ```
-- Move into the new worktree directory and begin work there.
-- Do not start editing until the shell is operating inside the new worktree directory and the worktree root has been verified.
-- When checking whether the target branch or worktree already exists, use direct git evidence instead of shell heuristics:
-  ```bash
-  git show-ref --verify --quiet refs/heads/<branch-name>
-  git worktree list --porcelain
-  ```
-- If branch creation or worktree creation fails in a way that leaves the state unclear, stop and re-read `git show-ref` plus `git worktree list --porcelain` before retrying; do not guess from wrapper output or compound shell conditionals.
-
-Use branch naming from `references/branch-naming.md`.
-
-### 4) Implement the planned tasks
-
-Use $implement-specs for the standard implementation workflow.
-
-Additionally:
-
-- When `preparation.md` exists, implement against its prepared baseline assumptions and avoid duplicating preparation tasks in the member spec.
-- When using targeted Rust `cargo test` commands, pass at most one positional test filter per invocation; if multiple selectors are needed, run separate commands or a broader confirmed selector.
-
-### 5) Backfill completion status
-
-Use $implement-specs for the standard backfill workflow.
-
-Additionally:
-
-- If preparation assumptions changed or were found missing, update `preparation.md` or stop for re-coordination instead of silently moving prerequisite work into the member spec.
-
-### 6) Commit changes
-
-Use $implement-specs for the standard commit workflow.
-
-### 7) Report completion
-
-See $implement-specs for the standard reporting format. Add the following context-specific details:
-
-- Note the spec-derived branch name and worktree location.
-- Confirm that the parent branch remains unaffected.
-
-## Working Rules
-
-- Always work in an isolated worktree to keep the parent checkout clean.
-- Treat the parent checkout as read-only for implementation work; use it only for inspection, worktree creation, or verification, never for file edits.
-- Treat an already-landed spec as complete work, not as a reason to recreate a duplicate worktree.
-- Keep the new branch based on the same parent branch as the worktree base; do not silently rebase the workflow onto a different branch.
-- Use the spec-set name as the canonical identifier for the branch and worktree unless the user explicitly asks for a different naming scheme.
-- When `preparation.md` exists, treat it as a prerequisite baseline owned outside the member spec; do not duplicate or alter its tasks unless explicitly requested.
-- Revert formatter-only edits outside the owned spec scope before the final commit so the worktree stays reviewable and merge-safe.
-- The shared working rules from $implement-specs also apply (complete all tasks, treat specs as truth, respect coordination.md, follow testing standards, no remote push unless asked).
+- **Cargo** (two filters ⇒ two commands): run `cargo test parser::` **and separately** `cargo test cache::`, not `cargo test parser:: cache::`.
 
 ## References
 
-- `references/branch-naming.md`: branch naming conventions
-- `enhance-existing-features`: implementation standards for brownfield work
-- `develop-new-features`: implementation standards for new feature work
+- `implement-specs`: shared lifecycle (read → implement → backfill → commit → report)
+- `references/branch-naming.md`: branch naming
+- `enhance-existing-features`, `develop-new-features`: implementation standards

package/maintain-project-constraints/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: maintain-project-constraints
-description: Create and maintain AGENTS.md/CLAUDE.md with the project's macro business goals, common development commands, and an index of all standardized project documentation under docs/. Use when AGENTS.md/CLAUDE.md is missing or may be outdated.
+description: >-
+  Maintain root `AGENTS.md` / `CLAUDE.md` with exactly three mirrored sections (unless the repo documents deliberate divergence): Common Development Commands traced to real scripts/Makefile targets, Project Business Goals capturing macro why/who/outcome, Project Documentation Index enumerating every standardized `docs/features`, `docs/architecture`, `docs/principles` file plus important root docs—purge invented commands, prune deleted paths, forbid stuffing feature lists into Goals.
+  Invoke after missing files, drift after refactors, or once `align-project-documents` reshapes `docs/`.
+  Bad: documenting `npm run magic` absent from `package.json`. Good: cite `npm test` with file reference. Bad: ten micro-features listed under Goals instead of the docs index…
 ---
 
 # Maintain Project Constraints
@@ -12,134 +15,79 @@ description: Create and maintain AGENTS.md/CLAUDE.md with the project's macro bu
 - Optional: none.
 - Fallback: not applicable.
 
-## Standards
+## Non-negotiables
 
-- Evidence: Infer project business goals and common commands from current code, configuration, and existing project documentation — not assumptions.
-- Execution: Read the entire codebase or existing project docs before writing; create or update only after building a concrete inventory.
-- Quality: Remove stale commands, paths, and references; keep AGENTS.md/CLAUDE.md focused on the three required sections only.
-- Output: Maintain a concise root-level `AGENTS.md`/`CLAUDE.md` with common development commands, macro business goals, and a project documentation index.
+- **MUST** derive commands and business purpose from **current** repo artifacts (`package.json`, `Makefile`, `bin/`, `scripts/`, `README`, `docs/features/`, code entrypoints)—**MUST NOT** invent flags, task names, or CLI paths.
+- **`AGENTS.md` / `CLAUDE.md` content** is **exactly three sections**—no extra tutorials, architecture essays, or style guides (those belong in `docs/`):
+  1. **Common Development Commands**
+  2. **Project Business Goals**
+  3. **Project Documentation Index**
+- **MUST** list **every** file under `docs/features/`, `docs/architecture/`, `docs/principles/` plus notable root docs (`README.md`, `CONTRIBUTING.md`, …) that exist; paths **MUST** exist on disk—**MUST NOT** stale links.
+- If **both** `AGENTS.md` and `CLAUDE.md` exist, the three sections **MUST** be **identical** between them unless the repo documents an intentional divergence (otherwise keep parity).
+- **Project Business Goals** = macro **why/for whom/outcome**—**MUST NOT** duplicate the feature inventory (index already points there).
 
-## Goal
+## Standards (summary)
 
-Keep `AGENTS.md`/`CLAUDE.md` accurate and synchronized with the current state of the repository, focused on helping agents understand the project's purpose, navigate its documentation, and run common development tasks.
+- **Evidence**: Scripts and docs on disk drive command list and index—no memory.
+- **Execution**: Inventory → draft three sections → verify paths → prune stray sections.
+- **Quality**: Scannable; no speculative architecture.
+- **Output**: Fresh root constraint files aligned with repo.
 
-## Trigger Conditions
+## Triggers
 
-Invoke this skill when:
+- Missing `AGENTS.md`/`CLAUDE.md`, post-change drift suspected, or after `align-project-documents` reshapes `docs/`.
 
-1. `AGENTS.md` or `CLAUDE.md` does not exist.
-2. `AGENTS.md` or `CLAUDE.md` exists but may have drifted after code changes, documentation updates, or workflow changes.
-3. After `align-project-documents` has updated the `docs/` structure and the document index needs to be refreshed.
+## Workflow
 
-## Required Output Format
+**Chain-of-thought:** **`Pause →`** before writing each section—if a command is uncertain, grep config before committing text.
 
-`AGENTS.md`/`CLAUDE.md` must contain exactly three sections:
+### 1) Inventory
 
-### 1. Common Development Commands
+- Parse command surfaces (`package.json` scripts, `Makefile`, CI, CLIs).
+- Enumerate `docs/features/`, `docs/architecture/`, `docs/principles/`; note root docs.
+  - **Pause →** Can I cite the **source line** (script name, target) for every command I plan to list?
 
-- Include only commands that are real, current, and useful in this repository.
-- Prefer repository-owned entry points: package scripts, CLIs, `bin/` programs, `scripts/`, `Makefile`, `justfile`, or equivalent task runners.
-- For each command, explain when to use it in one short phrase.
-- Prioritize commands that help an agent inspect, validate, build, test, or operate the repository.
-- Do not invent commands, aliases, flags, or task names not traceable to the repository.
+### 2) Business goals
 
-### 2. Project Business Goals
+- Prefer `README` + `docs/features/` tone; else infer from user-facing entrypoints—still **product-level sentences**, not file lists.
 
-- Describe the project's macro business purpose: what problem it solves, what outcome it aims to achieve, who it serves.
-- Write at the product or business level, not at the implementation level.
-- Keep it concise but self-contained — a reader should understand why the project exists without reading other documents.
+### 3) Write / update files
 
-### 3. Project Documentation Index
+- Create or overwrite **only** the three sections per file conventions (create missing file among `AGENTS.md`/`CLAUDE.md` per repo habit).
+  - **Pause →** Did any stray `## Installation` creep in—must delete if not part of repo’s mandated format?
 
-- List all standardized project documentation files under `docs/`.
-- Organize by category: `docs/features/`, `docs/architecture/`, `docs/principles/`.
-- For each document, provide the file path and a one-line description of what it covers.
-- List any additional root-level documentation files (e.g., `README.md`, `CONTRIBUTING.md`, `SECURITY.md`).
+### 4) Documentation index
 
-### Template Example
+- One line per file: `path — short purpose`. Mirror reality; drop deleted; add new.
 
-```markdown
-## Common Development Commands
+### 5) Verification
 
-- `npm test` — run the test suite.
-- `npm run build` — compile the project for production.
-- `apltk validate-skill-frontmatter` — validate every top-level `SKILL.md` frontmatter block.
+- Each command reproducible from declared config; every indexed path exists; both files match if both present; strip extra sections.
 
-## Project Business Goals
+## Sample hints
 
-This project enables users to manage and run reusable automation workflows.
-It solves the problem of scattered, inconsistent automation scripts by providing a unified catalog of versioned, validated skills.
+- **Command bad**: “`npm run magic` — deploy” when no script `magic` in `package.json`.
+- **Command OK**: `` `npm test` — runs Node test suite (see `package.json`) ``.
+- **Goals bad**: Listing ten micro-features → belongs in features index + separate files.
+- **Goals OK**: “This repo ships X for Y operators; primary outcome Z.”
+- **Index**: If `docs/features/auth.md` deleted, **remove** line same run.
 
-## Project Documentation Index
+## Template sketch
 
-### Features (`docs/features/`)
+```markdown
+## Common Development Commands
+- `…` — …
 
-- `docs/features/skill-management.md` — skill creation, editing, and lifecycle management
-- `docs/features/validation.md` — skill and configuration validation workflows
+## Project Business Goals
+…
 
+## Project Documentation Index
+### Features (`docs/features/`)
+- `…` — …
 ### Architecture (`docs/architecture/`)
-
-- `docs/architecture/skill-system.md` — skill loading, resolution, and execution model
-- `docs/architecture/validation-pipeline.md` — validation pipeline design
-
+- …
 ### Principles (`docs/principles/`)
-
-- `docs/principles/naming-conventions.md` — file and identifier naming rules
-- `docs/principles/dependency-management.md` — internal and external dependency rules
-
+- …
 ### Root Documents
-
-- `README.md` — project overview and quick start
+- `README.md` — …
 ```
-
-## Workflow
-
-### 1) Build factual understanding
-
-- Read the repository entry points, configuration, and command surfaces (`package.json`, `bin/`, `scripts/`, `Makefile`, etc.).
-- If standardized project documentation exists under `docs/`, read `docs/features/`, `docs/architecture/`, and `docs/principles/` to understand the documented capabilities and to build the index.
-- If `docs/` does not exist or is incomplete, read the source code directly to extract business goals and common commands.
-- Build a concrete inventory of:
-  - Every stable, repository-specific command.
-  - The project's macro business purpose (from docs, README, or inferred from the codebase's capabilities).
-  - Every file under `docs/` that should appear in the index.
-
-### 2) Extract macro business goals
-
-- Derive the project's business purpose from:
-  1. Existing documentation (`README.md`, `docs/features/`) if available.
-  2. The set of user-facing capabilities found in the codebase.
-- Write at the product level: what problem does this solve? who uses it? what outcome does it produce?
-- Do not restate implementation details or list features; the document index already points to feature docs.
-
-### 3) Write or update AGENTS.md/CLAUDE.md
-
-- If `AGENTS.md` exists, update it. If `CLAUDE.md` exists, update it. If both exist, update both with identical content for the three sections.
-- If neither exists, check for the repository's convention and create the appropriate file.
-- Write only the three sections: Common Development Commands, Project Business Goals, Project Documentation Index.
-- Do not add architecture descriptions, code style guidance, business flows, or any content that belongs in `docs/`.
-
-### 4) Maintain the project documentation index
-
-- Enumerate every file under `docs/features/`, `docs/architecture/`, and `docs/principles/`.
-- For each file, write a one-line description of what it covers.
-- List root-level documentation files (`README.md`, `CONTRIBUTING.md`, `SECURITY.md`, `CHANGELOG.md`, etc.) that exist in the repository.
-- Keep the index synchronized with the actual files on disk; remove entries for deleted files and add entries for new files.
-
-### 5) Quality checks before finishing
-
-- Verify every command in Common Development Commands is traceable to a repository entry point.
-- Verify Project Business Goals describes the macro purpose, not a feature list.
-- Verify every file listed in the Documentation Index exists on disk.
-- Verify the index covers all files under `docs/features/`, `docs/architecture/`, and `docs/principles/`.
-- If both `AGENTS.md` and `CLAUDE.md` exist, verify their content is consistent.
-- Remove any sections beyond the three required ones.
-
-## Writing Rules
-
-- Keep the document concise and scannable.
-- Use the repository's own terminology.
-- Do not speculate about architecture or implementation details.
-- In Project Business Goals, describe the macro purpose; for example, the user or business problem the project solves.
-- In the Documentation Index, prefer descriptive one-line summaries over bare file paths.
-- When both `AGENTS.md` and `CLAUDE.md` exist, keep their content identical for the three sections.

package/maintain-skill-catalog/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: maintain-skill-catalog
-description: Audit and maintain a repository of installable skills so the catalog stays internally consistent. Use when users ask to standardize `SKILL.md` structure across many skills, classify internal vs external skill dependencies, sync skill lists and external dependency docs, extract shared workflows into new skills, or fix catalog-wide validation/agent-config issues.
+description: >-
+  Maintain this SKILL catalog repo: reconcile `SKILL.md` frontmatter/`Dependencies`, `agents/openai.yaml`, README inventory, classify vendored vs external vs unpublished-local aliases, prefer extracting shared workflows over duplicating long prose, and always rerun `apltk validate-skill-frontmatter` plus `apltk validate-openai-agent-config` before finishing—never invent package names or installers for unverified deps.
+  Use when CI metadata breaks, users ask to “sync skills”, or dependency docs drift. Do not use for random application repos that are not this catalog layout.
+  Bad: marketing a `~/.claude` draft as an npm dependency… Good: label it “local optional” and link once in README instead of pasting the blurb into five skills…
 ---
 
 # Maintain Skill Catalog
@@ -9,60 +12,61 @@ description: Audit and maintain a repository of installable skills so the catalo
 
 - Required: none.
 - Conditional: `find-skills` when a dependency is external and the installation source is unknown.
-- Optional: `skill-creator` when splitting a repeated workflow into a new shared skill or significantly reshaping an existing skill.
-- Fallback: If an external dependency cannot be verified, leave it undocumented rather than guessing the package name or install command.
+- Optional: `skill-creator` when extracting a repeated workflow into a new shared skill or heavily reshaping a skill.
+- Fallback: If an external dependency cannot be verified, **MUST** document unknowns honestly—**MUST NOT** invent package names, install commands, or skill aliases.
 
-## Standards
+## Non-negotiables
 
-- Evidence: Read the actual skill folders, validation scripts, repository docs, and local installed skill names before changing dependency classifications or catalog docs.
-- Execution: Audit first, classify findings, make focused catalog updates, then run the repo validators before finishing.
-- Quality: Avoid duplicate skills, avoid rewording behavior without checking the implementation, distinguish aliases or local unpublished skills from true external dependencies, and enforce the repository's current metadata constraints such as `SKILL.md` frontmatter validity, description-length limits, and synchronized agent configs.
-- Output: Leave the catalog with synchronized skill metadata, dependency documentation, and validation status.
+- **MUST** read actual skill directories, validator scripts (`scripts/validate_*.py`, CI), `README.md`, and `agents/openai.yaml` patterns **before** reclassifying dependencies or rewriting catalog prose.
+- **MUST** treat each skill’s `## Dependencies` block as authoritative for skill-to-skill references; reconcile docs to match folders, not the reverse by guess.
+- **MUST** classify each dependency edge as: vendored-in-repo · local unpublished (not advertised as external) · external-with-install-guidance · alias-only (explain, don’t duplicate as separate dep).
+- **MUST NOT** duplicate skills or paste long prose into README without verifying whether a narrower edit or extraction fixes the repetition.
+- **MUST NOT** advertise a colleague’s unpublished `~/.codex/skills/...` name as if it were an npm-installable artifact unless verified.
+- After metadata or agent-config edits, **MUST** run **`apltk validate-skill-frontmatter`** and **`apltk validate-openai-agent-config`** (or fail the session with explanation if CLI unavailable)—**MUST NOT** declare the catalog consistent while validators fail.
+- If validator failures reveal a **systemic** gap, **MUST** prefer tightening the validator/CI in the **same** change set when appropriate, not only patching one skill ad hoc.
 
-## Goal
+## Standards (summary)
 
-Keep a skill repository coherent when many top-level skills evolve together.
+- **Evidence**: Folders + scripts + frontmatter reality; optional `~/.codex/skills` spot-check for external names.
+- **Execution**: Inventory → classify → minimal focused edits → validate → report.
+- **Quality**: One skill one purpose; naming matches folder; agent configs synchronized.
+- **Output**: Updated lists/docs + green validators + explicit unknowns.
 
 ## Workflow
 
-### 1) Inventory the catalog before editing
+**Chain-of-thought:** Answer **`Pause →`** before moving to the next subsection; validator red **MUST** block “done.”
 
-- List the tracked top-level skill directories and read the relevant `SKILL.md` files before deciding that a new skill is needed.
-- Check whether the requested workflow already exists under another name or can be handled by a focused update.
-- Read current `README.md`, `AGENTS.md/CLAUDE.md/CLAUDE.md`, validator scripts, and any existing dependency notes that may need synchronization.
-- When the task involves external dependencies, inspect local installed skills under `~/.codex/skills` first to confirm the exact skill names.
+### 1) Inventory
 
-### 2) Audit dependency declarations and shared conventions
+- Enumerate top-level skill dirs (`SKILL.md` present); read touched `SKILL.md` files before inventing merges or new skills.
+- Read `README.md`, `AGENTS.md`/`CLAUDE.md`, and existing dependency notes.
+  - **Pause →** Is the requested change already satisfied by renaming or merging **existing** skill text instead of adding a sibling skill?
+  - **Pause →** Which validator script actually enforces description length and keys—did I open its source?
 
-- Use the standardized `## Dependencies` section as the source of truth for skill-to-skill relationships.
-- Read the current validator scripts before changing frontmatter-heavy files so metadata limits come from implementation rather than memory.
-- Classify each dependency as:
-  - vendored in this repository
-  - local/private skill that should not be documented as external
-  - external skill that needs install guidance
-  - alias/compatibility name that should be explained but not treated as a separate dependency
-- Verify exact external skill names before editing docs; do not invent pluralizations or package names.
-- If multiple skills repeat the same workflow, prefer extracting that shared portion into a dedicated skill instead of duplicating instructions.
+### 2) Audit dependencies and conventions
 
-### 3) Update catalog docs and skill metadata carefully
+- Align `## Dependencies` across skills with shared vocabulary (`Required` / `Conditional` / `Optional` / `Fallback`).
+- Exact external strings only—verify spelling/plural vs installed tree.
+- Repeated workflows ⇒ prefer **extract** to new skill (`skill-creator`) over copy-paste.
+  - **Pause →** Would classifying dep X as “external” confuse installers—could it actually be repo-vendored or optional?
 
-- Keep edits minimal and repo-wide only where necessary.
-- Update `README.md` skill lists and external dependency sections when the catalog actually changes.
-- Update `AGENTS.md/CLAUDE.md` when the repository gains or loses a user-visible capability or a standing convention changes.
-- When creating a new shared skill, align naming, frontmatter, `agents/openai.yaml`, and any lightweight README with neighboring skills.
-- When a failure comes from validator drift or a metadata constraint that was not caught early, tighten the validator or CI path in the same change instead of only fixing the offending skill text.
-- Do not treat unpublished local skills as external dependencies just because they are not yet installed elsewhere.
+### 3) Apply catalog edits
 
-### 4) Validate the catalog after changes
+- Minimal diffs; update `README` skill lists and external-dep sections **only when** inventory changed facts.
+- New shared skill: kebab-case folder = frontmatter `name`; add `agents/openai.yaml` following neighbors.
+  - **Pause →** Did I treat a **template** path under `references/` as a runtime skill—classification error?
 
-- Run:
-  - `apltk validate-skill-frontmatter`
-  - `apltk validate-openai-agent-config`
-- If the change touched installer or repo-discovery behavior, verify the relevant install scripts or discovery logic as well.
-- Resolve validation failures before finishing; missing `agents/openai.yaml`, stale prompt references, and mismatched skill names are catalog bugs, not follow-up work.
+### 4) Validate
 
-### 5) Record conclusions explicitly
+- Run `apltk validate-skill-frontmatter` and `apltk validate-openai-agent-config`. If installer/discovery scripts changed behavior, smoke the paths they document.
+  - **Pause →** Any skill missing `agents/openai.yaml` or stale tool names—still acceptable for this repo’s rules?
 
-- Summarize which skills were audited, which conventions were updated, and which dependencies were confirmed as external.
-- Call out any unresolved unknowns, such as an external dependency whose install source could not be verified.
-- When a user correction changes the catalog rules, encode that rule in the skill or repository docs so the same mistake does not recur.
+### 5) Report
+
+- Skills touched, conventions updated, external deps verified vs unknown; encode user-stated repo rules into skill or README so regressions recur less.
+
+## Sample hints
+
+- **Classification**: Skill A says `Conditional: Foo` but `Foo` lives only under `~/.claude/` unpublished → document as **local optional**, not “install Foo from npm.”
+- **Validator**: frontmatter `description` 1100 chars → expect **fail** if limit 1024—fix text, don’t disable check.
+- **Anti-pattern**: “We should mention skill X everywhere” → add **once** to README index + Dependencies of callers, not five duplicate paragraphs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laitszkin/apollo-toolkit",
-  "version": "3.8.4",
+  "version": "3.9.0",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",