@laitszkin/apollo-toolkit 3.11.5 → 3.11.7

package/AGENTS.md

@@ -38,6 +38,7 @@ This repository enables users to install and run a curated set of reusable agent
 - Users can run a shared submission-readiness pass that synchronizes changelog, project docs, `AGENTS.md`, and completed plan archives before commit, push, PR creation, or release.
 - Users can learn new or improved skills from recent Codex conversation history.
 - Users can audit and maintain the skill catalog itself, including dependency classification and shared-skill extraction decisions.
+- Users can optimize existing agent skills by deriving the intended deliverable, tightening acceptance criteria, and rewriting `SKILL.md` into a leaner structure backed by extracted references.
 - Users can implement approved spec planning sets directly in the current checkout and commit them to the active branch.
 - Users can implement approved spec planning sets inside isolated git worktrees and keep the parent checkout clean.
 - Users can coordinate approved multi-spec implementation batches by assigning each spec directory to an independent worktree-backed subagent with bounded concurrency.

package/CHANGELOG.md

@@ -10,6 +10,36 @@ All notable changes to this repository are documented in this file.
 
 ### Fixed
 
+## [v3.11.7] - 2026-05-12
+
+### Added
+
+- Add `optimise-skill`, a new catalog skill that reads a target skill and its supporting files, derives the intended deliverable and acceptance criteria, and rewrites the skill into a tighter `goal / acceptance criteria / workflow / examples / references` structure for higher-signal agent execution.
+
+### Changed
+
+- Catalog docs now include `optimise-skill`, and its bundled example reference path is normalized to match the shipped file name.
+
+### Fixed
+
+## [v3.11.6] - 2026-05-12
+
+### Added
+
+- Tests: spec-mode batch-root overlay writes, combined batch diff rendering, legacy HTML-only batch diff fallback, repeated spec render cleanup, and multi-step `undo` coverage for the declarative atlas CLI.
+
+### Changed
+
+- `apltk architecture --spec <spec_dir>` now keeps the existing single-spec layout for standalone plans, but batch member paths resolve to one shared `architecture_diff/` beside `coordination.md` so the whole batch maintains a single overlay and rendered architecture diff.
+- `generate-spec` and `spec-to-project-html` now document the shared batch-root overlay behavior and tighten architecture-diff completion criteria: all intended cross-feature edges, feature-to-feature relationships, and sub-module relationships must be declared explicitly through the CLI instead of being left implicit in prose.
+- Spec-mode atlas persistence now derives overlay state from the merged proposed-after graph, which lets repeated edits collapse back to a minimal diff automatically and adds `apltk architecture undo --steps <n>` for multi-step rollback.
+
+### Fixed
+
+- `apltk architecture diff` now renders batch specs as one combined macro/viewer result instead of showing separate incomplete macro pages per member spec.
+- `apltk architecture diff` preserves compatibility with legacy batch artifacts that only contain rendered HTML plus `_removed.txt`, instead of silently dropping those member diffs when atlas overlay state is absent.
+- Spec-mode scoped renders now clean stale HTML pages and removal state correctly, preventing repeated render/diff runs from crashing on already-removed pages or leaving ghost overlay output behind.
+
 ## [v3.11.5] - 2026-05-12
 
 ### Added

package/README.md

@@ -41,6 +41,7 @@ A curated skill catalog for Codex, OpenClaw, Trae, Agents, and Claude Code with
 - open-source-pr-workflow
 - openai-text-to-image-storyboard
 - openclaw-configuration
+- optimise-skill
 - recover-missing-plan
 - record-spending
 - resolve-review-comments

package/generate-spec/SKILL.md

@@ -1,11 +1,14 @@
 ---
 name: generate-spec
 description: >-
-  Author docs/plans trees: run `apltk create-specs`, hydrate `spec/tasks/checklist/contract/design` (+ `coordination.md`/`preparation.md` when parallel/prep dictates), cite official docs for external deps, plan tests via **`test-case-strategy`**, block code edits until explicit user approval.
-  Architecture deltas use `apltk architecture --spec <spec_dir> …` (**flags: `apltk architecture --help`**) → overlay under `<spec_dir>/architecture_diff/`; **`apltk architecture diff`** pages every `docs/plans/**/architecture_diff/` vs the base atlas — never hand-edit `architecture_diff/`.
-  Use when drafting/refreshing specs or restructuring batches — not when executing approved plans (use **`implement-specs*`** instead).
-  Reject vague `tasks.md` missing file/mutation/verifier; SPLIT >3-module scope; never overwrite a neighbor `{change}`.
-  Bad: `- [ ] Add tests`… OK: `- [ ] src/auth/scope.rs — deny unknown scopes — Verify: cargo test scope::defaults`…
+  Author docs/plans trees: run `apltk create-specs`, fill `spec/tasks/checklist/contract/design`
+  (+ `coordination.md`/`preparation.md` for batches), cite official docs, plan tests via
+  **`test-case-strategy`**, and block code edits until approval. Architecture deltas use
+  `apltk architecture --spec <spec_dir> …`: single specs write under `<spec_dir>/architecture_diff/`,
+  while batch member paths resolve to the shared batch-root `architecture_diff/` beside
+  `coordination.md`; `apltk architecture diff` renders the before/after viewer. Use for
+  drafting/refreshing specs or restructuring batches, not execution. Reject vague `tasks.md`
+  rows and split scope beyond 3 modules.
 ---
 
 # Generate Spec
@@ -27,7 +30,7 @@ description: >-
 - **`tasks.md` checklist items**: **every** `- [ ]` **MUST** specify (a) concrete file/function target, (b) specific modification and expected outcome, (c) a verification hook—**no** vague rows (`Implement integration`, `Add tests`). Forbidden vague items **MUST** be rewritten before approval.
 - **MUST** use `test-case-strategy` when planning non-trivial logic tests and checklist mapping (test IDs, drift checks). Every **non-trivial** `tasks.md` implementation item **MUST** name a focused unit drift check, another concrete verification hook, or **`N/A`** with a concrete reason.
 - **MUST NOT** modify implementation code before **explicit user approval** of the spec set. Clarifications **MUST** sync across affected files and **MUST** re-trigger approval. If scope becomes a **different issue**, **MUST** stop editing the old set and create a **new** `change_name`.
-- **MUST** when the proposed change touches the architecture surface (feature / sub-module add / rename / remove, edge add / remove, variable rows, function I/O rows, internal dataflow / error deltas), declare the proposed-after state **only** through `apltk architecture --spec <spec_dir> …` using the exact verbs, subverbs, and flags from **`apltk architecture --help`** (this file must not be treated as the command list). The CLI writes overlay YAML to `<spec_dir>/architecture_diff/atlas/` and renders only the affected proposed-after HTML pages under `<spec_dir>/architecture_diff/`. **`apltk architecture diff`** then builds a paginated **before/after viewer**: it walks every `docs/plans/**/architecture_diff/` tree, pairs each overlay HTML path with the matching file under `resources/project-architecture/` when it exists, and labels pages **modified**, **added**, or **removed** (via `_removed.txt` / removal manifests) so reviewers can scroll the whole architecture delta without opening files by hand. **MUST NOT** hand-author anything under `architecture_diff/**` — the renderer owns layout, DOM, CSS, ARIA, and pan/zoom. For batch specs the overlay lives in **each member spec’s own directory** only — **MUST NOT** duplicate overlay at the batch root. Use this skill’s `references/TEMPLATE_SPEC.md` for field/enum schema; use `init-project-html/SKILL.md` for semantic rules (**subagent gate** + edge kinds + dataflow integrity). When using subagents to draft atlas overlay, the authoring agent **MUST** wait until **all** feature subagents finish before declaring cross-feature **`edge`** (or overlay **`meta`** / **`actor`** that only exists to stitch features), matching `init-project-html` / `spec-to-project-html`.
+- **MUST** when the proposed change touches the architecture surface (feature / sub-module add / rename / remove, edge add / remove, variable rows, function I/O rows, internal dataflow / error deltas), declare the proposed-after state **only** through `apltk architecture --spec <spec_dir> …` using the exact verbs, subverbs, and flags from **`apltk architecture --help`** (this file must not be treated as the command list). The CLI writes overlay YAML to `<spec_dir>/architecture_diff/atlas/` and renders only the affected proposed-after HTML pages under `<spec_dir>/architecture_diff/` for single-spec plans. For batch plans, passing any member spec path to `--spec` resolves to the shared batch-root overlay beside `coordination.md`, so the whole batch maintains **one** `architecture_diff/atlas/` and **one** rendered architecture diff. **`apltk architecture diff`** then builds a paginated **before/after viewer**: it walks every `docs/plans/**/architecture_diff/` tree, pairs each overlay HTML path with the matching file under `resources/project-architecture/` when it exists, and labels pages **modified**, **added**, or **removed** (via `_removed.txt` / removal manifests) so reviewers can scroll the whole architecture delta without opening files by hand. **MUST NOT** hand-author anything under `architecture_diff/**` — the renderer owns layout, DOM, CSS, ARIA, and pan/zoom. Use this skill’s `references/TEMPLATE_SPEC.md` for field/enum schema; use `init-project-html/SKILL.md` for semantic rules (**subagent gate** + edge kinds + dataflow integrity). When using subagents to draft atlas overlay, the authoring agent **MUST** wait until **all** feature subagents finish before declaring cross-feature **`edge`** (or overlay **`meta`** / **`actor`** that only exists to stitch features), matching `init-project-html` / `spec-to-project-html`.
 - Write prose in the **user’s language** by default; keep requirement/task/test IDs traceable across `spec.md`, `tasks.md`, and `checklist.md`.
 - **MUST** use **kebab-case** `change_name`; **MUST NOT** use spaces or arbitrary special characters in names.
 
@@ -85,15 +88,15 @@ Always materialize: `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `desig
 
 When the spec changes a feature module, sub-module, edge, variable row, function I/O row, internal dataflow, or error row:
 
-1. **Discover commands:** run **`apltk architecture --help`** in the target workspace; use that output for every `add` / `set` / `remove` / `reorder` spelling and required flag. Do not copy long command tables from skills — they go stale.
-2. **Declare proposed-after state** with `apltk architecture --spec <spec_dir> …` for each mutation (pass `--no-render` while batching if you prefer a single render at the end).
-3. **`apltk architecture render --spec <spec_dir>`** — emits/updates only the HTML files touched by this overlay plus assets.
-4. **`apltk architecture validate --spec <spec_dir>`** — **MUST** return OK before the spec is approval-ready (resolve dangling edges, unknown enums, bad dataflow references).
-5. **`apltk architecture diff`** — **MUST** run before hand-off when atlas changed; confirm the paginated viewer shows sensible **modified** / **added** / **removed** counts and that each interesting path pairs correctly (base `resources/project-architecture/…` vs `<spec_dir>/architecture_diff/…`). A page appearing as **remove + add** instead of **modified** usually means a **slug rename** was split wrong — fix with intentional remove+add or a single coherent mutation sequence.
+**Completion standard:** the overlay is not complete until every intended cross-feature **edge**, every feature-to-feature dependency or call/return relationship, and every sub-module-to-sub-module relationship inside the affected scope has been declared precisely through the CLI. It is **not** acceptable to leave relationship structure implied only by prose in `spec.md` / `design.md`; the architecture diff must explicitly express the real proposed-after topology.
 
-**Where files land:** overlay YAML under `<spec_dir>/architecture_diff/atlas/`; rendered proposed-after HTML under `<spec_dir>/architecture_diff/`. Cross-feature edges whose far endpoint exists only in the **base** atlas still resolve when merged — but you **must** `validate` to catch mistakes.
+1. **Discover commands:** run **`apltk architecture --help`** in the target workspace; use that output for every `add` / `set` / `remove` / `reorder` spelling and required flag. Do not copy long command tables from skills — they go stale.
+2. **Declare proposed-after state** with `apltk architecture --spec <spec_dir> …` for each mutation (pass `--no-render` while batching if you prefer a single render at the end). In a batch, keep using the member spec path; the CLI resolves writes to the batch-root `architecture_diff/` beside `coordination.md`.
+3. **`apltk architecture render --spec <spec_dir>`** — emits/updates only the HTML files touched by this overlay plus assets. In a batch, this updates the shared batch-root render.
+4. **`apltk architecture validate --spec <spec_dir>`** — **MUST** return OK before the spec is approval-ready (resolve dangling edges, unknown enums, bad dataflow references). In a batch, this validates the shared batch-root overlay.
+5. **`apltk architecture diff`** — **MUST** run before hand-off when atlas changed; confirm the paginated viewer shows sensible **modified** / **added** / **removed** counts and that each interesting path pairs correctly (base `resources/project-architecture/…` vs the spec or batch-root `architecture_diff/…`). Use this pass to verify that the rendered graph actually contains the full intended relationship set: all relevant feature-level seams, all required sub-module seams, and no missing edge that the design prose depends on. A page appearing as **remove + add** instead of **modified** usually means a **slug rename** was split wrong — fix with intentional remove+add or a single coherent mutation sequence.
 
-**Batch specs:** each `<spec_dir>` is one member directory under `docs/plans/...`; **never** duplicate overlay at the batch root.
+**Where files land:** single-spec plans write overlay YAML under `<spec_dir>/architecture_diff/atlas/` and rendered proposed-after HTML under `<spec_dir>/architecture_diff/`. Batch plans write both under the batch root beside `coordination.md`, even when the CLI call uses a member spec path. Cross-feature edges whose far endpoint exists only in the **base** atlas still resolve when merged — but you **must** `validate` to catch mistakes.
 
 **Subagent coordination:** if multiple features are drafted in parallel, **do not** declare cross-feature **`edge`** (or overlay **`meta` / `actor`** used only to stitch features) until **all** feature workers report done — see `init-project-html/SKILL.md` Rule 3 and `spec-to-project-html`.
 
@@ -102,6 +105,7 @@ When the spec changes a feature module, sub-module, edge, variable row, function
 - **Pause →** Did I touch any file under `architecture_diff/` by hand? Revert and re-run the CLI verb instead.
 - **Pause →** Does `apltk architecture validate --spec <spec_dir>` return OK?
 - **Pause →** Does `apltk architecture diff` pair the spec’s pages correctly?
+- **Pause →** Have I explicitly declared every intended edge, feature-to-feature relationship, and sub-module relationship in the CLI output, or am I still relying on prose to imply missing structure?
 
 ### 4) Clarifications and approval
 

package/generate-spec/agents/openai.yaml

@@ -4,7 +4,7 @@ interface:
   default_prompt: >-
     Use $generate-spec to create or update single-spec plans under docs/plans/<date>/<change_name>/ or parallel batches under docs/plans/<date>/<batch_name>/<change_name>/ with shared coordination.md and, only when specs cannot be parallel-safe without prior shared work, minimal non-business preparation.md; treat references/templates/*.md as binding format; member specs assume preparation finished—do not duplicate preparation tasks; surface collisions early and resolve ownership via coordination.md; fill BDD in spec.md; integrate $test-case-strategy into tasks/checklists.
     **Critical layering:** design.md + contract.md are higher-level guiding context only (architecture + cite-backed external truth; coarse INT-### / EXT-### anchors). tasks.md MUST be the ONLY enumerated runnable queue with path-level edits and verification hooks—derive tasks FROM spec + design + contract WITHOUT mirroring checklist rows into design/contract; optionally cite INT/EXT on task lines for traceability—never duplicate task choreography inside design.md or contract.md.
-    **Architecture overlay + diff:** When the spec touches atlas surface (feature/sub-module, edges, function/variable rows, dataflow, errors), declare proposed-after state ONLY via `apltk architecture --spec <spec_dir> …`. **Exact verbs/flags: ALWAYS `apltk architecture --help`.** CLI writes `<spec_dir>/architecture_diff/atlas/` + renders affected HTML under `<spec_dir>/architecture_diff/`. NEVER hand-author `architecture_diff/**`.
-    After mutations: `render --spec`, `validate --spec` (must be OK pre-approval). **`apltk architecture diff`** opens the paginated before/after viewer over all `docs/plans/**/architecture_diff/` vs base `resources/project-architecture/` — run it when atlas changed; verify modified/added/removed pairing.
-    Batch specs: one overlay per member directory—never at batch root. If subagents draft multiple features: **wait until ALL finish** before cross-feature `edge` / stitching `meta` / `actor` (same gate as $init-project-html / $spec-to-project-html).
+    **Architecture overlay + diff:** When the spec touches atlas surface (feature/sub-module, edges, function/variable rows, dataflow, errors), declare proposed-after state ONLY via `apltk architecture --spec <spec_dir> …`. **Exact verbs/flags: ALWAYS `apltk architecture --help`.** Single-spec plans write `<spec_dir>/architecture_diff/atlas/` + rendered HTML under `<spec_dir>/architecture_diff/`. Batch plans resolve any member `--spec` path to the shared batch-root `architecture_diff/` beside `coordination.md`, so the whole batch keeps one architecture diff. NEVER hand-author `architecture_diff/**`.
+    Completion standard for atlas work: every intended cross-feature edge, every feature-to-feature relationship, and every sub-module relationship in scope must be expressed precisely through the CLI output — not left implicit in prose. After mutations: `render --spec`, `validate --spec` (must be OK pre-approval). **`apltk architecture diff`** opens the paginated before/after viewer over all `docs/plans/**/architecture_diff/` vs base `resources/project-architecture/` — run it when atlas changed; verify modified/added/removed pairing and confirm the rendered graph contains the full intended relationship set.
+    If subagents draft multiple features: **wait until ALL finish** before cross-feature `edge` / stitching `meta` / `actor` (same gate as $init-project-html / $spec-to-project-html).
     Field/enums: this skill's references/TEMPLATE_SPEC.md. Semantics: $init-project-html SKILL.md.

package/init-project-html/lib/atlas/cli.js

@@ -23,7 +23,7 @@
 //
 // Global flags:
 //   --project <root>     project root; creates resources/project-architecture/ if missing
-//   --spec <spec_dir>    spec directory; mutations go to <spec_dir>/architecture_diff/atlas/
+//   --spec <spec_dir>    single specs write to <spec_dir>/architecture_diff/atlas/; batch member paths resolve to the coordination.md root
 //   --no-render          skip auto-render after a mutation
 //   --no-open            for open/diff: skip launching the browser
 //   --out <dir>          for diff: override viewer output directory
@@ -41,6 +41,7 @@ const ATLAS_INDEX_REL = path.join(ATLAS_REL, 'index.html');
 const ATLAS_DIRNAME = stateLib.ATLAS_DIRNAME;
 const DIFF_DIRNAME = 'architecture_diff';
 const PLANS_REL = path.join('docs', 'plans');
+const COORDINATION_FILE = 'coordination.md';
 const REMOVED_TXT = '_removed.txt';
 const DEFAULT_DIFF_OUT_REL = path.join('.apollo-toolkit', 'architecture-diff');
 
@@ -63,12 +64,12 @@ Verbs:
   meta set                              edit meta.title / meta.summary
   actor add|remove                      manage top-level actors
   validate                              run schema + referential checks
-  undo                                  revert the most recent mutation
+  undo                                  revert the most recent mutation (use --steps <n> for multi-step rollback)
   help                                  show this help
 
 Global flags:
   --project <root>                      explicit project root (default: nearest ancestor with atlas markers, else cwd); missing directories under resources/project-architecture/ are created automatically
-  --spec <spec_dir>                     mutations write to <spec_dir>/architecture_diff/atlas/
+  --spec <spec_dir>                     single specs write to <spec_dir>/architecture_diff/atlas/; batch member paths write to the coordination.md root
   --no-render                           skip auto-render after a mutation
   --no-open                             for open/diff: skip launching the browser
   --out <dir>                           for diff: override viewer output directory
@@ -81,6 +82,7 @@ Examples:
   apltk architecture dataflow add --feature register --submodule api --step "Validate body" --fn handlePost --reads "body" --writes "token"
   apltk architecture --spec docs/plans/2026-05-11/add-2fa submodule set --feature register --slug api --role "..."
   apltk architecture validate
+  apltk architecture undo --steps 3 --spec docs/plans/2026-05-11/add-2fa
   apltk architecture diff
 `;
 
@@ -171,7 +173,15 @@ function resolveProjectRoot(flags) {
 
 function specOverlayDir(projectRoot, specFlag) {
   const specDir = path.isAbsolute(String(specFlag)) ? String(specFlag) : path.resolve(projectRoot, String(specFlag));
-  return { specDir, overlayDir: path.join(specDir, DIFF_DIRNAME, ATLAS_DIRNAME), htmlOutDir: path.join(specDir, DIFF_DIRNAME) };
+  const plansRoot = path.join(projectRoot, PLANS_REL);
+  const batchRoot = fs.existsSync(path.join(specDir, COORDINATION_FILE)) ? specDir : findBatchRoot(specDir, plansRoot);
+  const rootDir = batchRoot || specDir;
+  return {
+    specDir,
+    rootDir,
+    overlayDir: path.join(rootDir, DIFF_DIRNAME, ATLAS_DIRNAME),
+    htmlOutDir: path.join(rootDir, DIFF_DIRNAME),
+  };
 }
 
 function baseAtlasDir(projectRoot) {
@@ -207,26 +217,21 @@ function ensureBaseAtlasDir(projectRoot) {
 async function performMutation(projectRoot, flags, action, args, mutate) {
   const isSpec = Boolean(flags.spec);
   const base = stateLib.load(baseAtlasDir(projectRoot));
-  let overlay = null;
   let merged = base;
-  let touchedFeatureSlugs = new Set();
 
   if (isSpec) {
     const { overlayDir } = specOverlayDir(projectRoot, flags.spec);
-    overlay = stateLib.loadOverlay(overlayDir);
+    const overlay = stateLib.loadOverlay(overlayDir);
     merged = stateLib.mergeOverlay(base, overlay);
     const before = JSON.parse(JSON.stringify({ base, overlay }));
-    const result = mutate(merged, base, overlay) || {};
-    if (result.touchedFeatures) for (const slug of result.touchedFeatures) touchedFeatureSlugs.add(slug);
+    mutate(merged, base, overlay);
     stateLib.writeUndoSnapshot(overlayDir, before);
-    syncOverlayFromMerged({ base, overlay, merged, touchedFeatureSlugs, removalsHint: result.removalsHint });
-    stateLib.saveOverlay(overlayDir, overlay);
+    stateLib.saveOverlay(overlayDir, stateLib.deriveOverlay(base, merged));
     stateLib.appendHistory(overlayDir, { action, args, mode: 'spec' });
   } else {
     ensureBaseAtlasDir(projectRoot);
     const before = JSON.parse(JSON.stringify({ base }));
-    const result = mutate(base, base, null) || {};
-    if (result.touchedFeatures) for (const slug of result.touchedFeatures) touchedFeatureSlugs.add(slug);
+    mutate(base, base, null);
     stateLib.writeUndoSnapshot(baseAtlasDir(projectRoot), before);
     stateLib.save(baseAtlasDir(projectRoot), base);
     stateLib.appendHistory(baseAtlasDir(projectRoot), { action, args, mode: 'base' });
@@ -237,47 +242,6 @@ async function performMutation(projectRoot, flags, action, args, mutate) {
   }
 }
 
-function syncOverlayFromMerged({ base, overlay, merged, touchedFeatureSlugs, removalsHint }) {
-  // Compare merged top-level fields against base; if they differ, sync into overlay.
-  if (JSON.stringify(merged.meta || {}) !== JSON.stringify(base.meta || {})) overlay.meta = merged.meta;
-  if (JSON.stringify(merged.actors || []) !== JSON.stringify(base.actors || [])) overlay.actors = merged.actors || [];
-  if (JSON.stringify(merged.edges || []) !== JSON.stringify(base.edges || [])) overlay.edges = merged.edges || [];
-
-  const baseOrder = (base.features || []).map((f) => f.slug);
-  const mergedOrder = (merged.features || []).map((f) => f.slug);
-  if (JSON.stringify(baseOrder) !== JSON.stringify(mergedOrder)) {
-    overlay.featureOrder = mergedOrder;
-  }
-
-  // Persist touched (or simply differing) features into overlay.features
-  const baseFeatureMap = new Map((base.features || []).map((f) => [f.slug, f]));
-  const mergedFeatureMap = new Map((merged.features || []).map((f) => [f.slug, f]));
-  for (const slug of touchedFeatureSlugs) {
-    if (!mergedFeatureMap.has(slug)) continue;
-    const baseFeat = baseFeatureMap.get(slug);
-    const mergedFeat = mergedFeatureMap.get(slug);
-    if (!baseFeat || JSON.stringify(baseFeat) !== JSON.stringify(mergedFeat)) {
-      overlay.features[slug] = mergedFeat;
-    }
-  }
-  // Apply hinted removals
-  if (removalsHint) {
-    if (Array.isArray(removalsHint.features)) {
-      const seen = new Set(overlay.removed.features || []);
-      for (const slug of removalsHint.features) seen.add(slug);
-      overlay.removed.features = [...seen];
-      // also drop from overlay.features if present
-      for (const slug of removalsHint.features) delete overlay.features[slug];
-    }
-    if (Array.isArray(removalsHint.submodules)) {
-      const seen = new Map();
-      for (const item of overlay.removed.submodules || []) seen.set(`${item.feature}::${item.submodule}`, item);
-      for (const item of removalsHint.submodules) seen.set(`${item.feature}::${item.submodule}`, item);
-      overlay.removed.submodules = [...seen.values()];
-    }
-  }
-}
-
 async function runRender({ projectRoot, flags }) {
   if (flags.spec) {
     const { overlayDir, htmlOutDir } = specOverlayDir(projectRoot, flags.spec);
@@ -642,9 +606,14 @@ async function verbValidate(flags, projectRoot, io) {
 
 async function verbUndo(flags, projectRoot, io) {
   const dir = flags.spec ? specOverlayDir(projectRoot, flags.spec).overlayDir : baseAtlasDir(projectRoot);
-  const snapshot = stateLib.readUndoSnapshot(dir);
+  const stepsRaw = flags.steps === undefined ? 1 : Number(flags.steps);
+  if (!Number.isInteger(stepsRaw) || stepsRaw < 1) {
+    io.stderr.write('--steps must be a positive integer.\n');
+    return 1;
+  }
+  const snapshot = stateLib.consumeUndoSnapshot(dir, stepsRaw);
   if (!snapshot) {
-    io.stderr.write('No undo snapshot found.\n');
+    io.stderr.write(stepsRaw === 1 ? 'No undo snapshot found.\n' : `Unable to undo ${stepsRaw} steps; history is shorter.\n`);
     return 1;
   }
   if (flags.spec) {
@@ -655,9 +624,8 @@ async function verbUndo(flags, projectRoot, io) {
     stateLib.save(baseAtlasDir(projectRoot), snapshot.base);
     stateLib.appendHistory(baseAtlasDir(projectRoot), { action: 'undo', mode: 'base' });
   }
-  stateLib.clearUndoSnapshot(dir);
   if (!flags['no-render']) await runRender({ projectRoot, flags });
-  io.stdout.write('atlas: undo applied\n');
+  io.stdout.write(`atlas: undo applied (${stepsRaw} step${stepsRaw === 1 ? '' : 's'})\n`);
   return 0;
 }
 
@@ -678,36 +646,27 @@ async function verbOpen(flags, projectRoot, io) {
 async function verbDiff(flags, projectRoot, io) {
   const outDir = flags.out ? path.resolve(String(flags.out)) : path.join(projectRoot, DEFAULT_DIFF_OUT_REL);
   fs.mkdirSync(outDir, { recursive: true });
+  const changes = await collectDiffChanges({ projectRoot, outDir });
 
+  const html = renderDiffViewer({ changes, projectRoot, outDir });
+  const indexPath = path.join(outDir, 'index.html');
+  fs.writeFileSync(indexPath, html, 'utf8');
+  io.stdout.write(`${indexPath}\n`);
+  io.stdout.write(`Diff pages: ${changes.length} (modified=${changes.filter((c) => c.kind === 'modified').length}, added=${changes.filter((c) => c.kind === 'added').length}, removed=${changes.filter((c) => c.kind === 'removed').length})\n`);
+  if (!flags['no-open']) openInBrowser(indexPath);
+  return 0;
+}
+
+async function collectDiffChanges({ projectRoot, outDir }) {
   const plansRoot = path.join(projectRoot, PLANS_REL);
-  const diffDirs = walkArchitectureDiffDirs(plansRoot);
-  const resourcesRoot = path.join(projectRoot, ATLAS_REL);
+  const groups = groupDiffDirsByBatch({ projectRoot, plansRoot });
   const changes = [];
 
-  for (const diffDir of diffDirs) {
-    const specDir = path.dirname(diffDir);
-    const specLabel = path.relative(projectRoot, specDir);
-    for (const after of walkAfterStateHtml(diffDir)) {
-      const beforeAbs = path.join(resourcesRoot, after.rel);
-      const beforeExists = fs.existsSync(beforeAbs);
-      changes.push({
-        kind: beforeExists ? 'modified' : 'added',
-        rel: after.rel,
-        spec: specLabel,
-        beforePath: beforeExists ? path.relative(projectRoot, beforeAbs) : null,
-        afterPath: path.relative(projectRoot, after.abs),
-      });
-    }
-    for (const removedRel of readRemovedManifest(diffDir)) {
-      const beforeAbs = path.join(resourcesRoot, removedRel);
-      if (!fs.existsSync(beforeAbs)) continue;
-      changes.push({
-        kind: 'removed',
-        rel: removedRel,
-        spec: specLabel,
-        beforePath: path.relative(projectRoot, beforeAbs),
-        afterPath: null,
-      });
+  for (const group of groups) {
+    if (group.kind === 'batch') {
+      changes.push(...await collectBatchGroupChanges({ projectRoot, outDir, group }));
+    } else {
+      changes.push(...collectSingleSpecChanges({ projectRoot, specDir: group.specDir, specLabel: group.label }));
     }
   }
 
@@ -716,14 +675,171 @@ async function verbDiff(flags, projectRoot, io) {
     if (a.kind !== b.kind) return a.kind.localeCompare(b.kind);
     return a.rel.localeCompare(b.rel);
   });
+  return changes;
+}
 
-  const html = renderDiffViewer({ changes, projectRoot, outDir });
-  const indexPath = path.join(outDir, 'index.html');
-  fs.writeFileSync(indexPath, html, 'utf8');
-  io.stdout.write(`${indexPath}\n`);
-  io.stdout.write(`Diff pages: ${changes.length} (modified=${changes.filter((c) => c.kind === 'modified').length}, added=${changes.filter((c) => c.kind === 'added').length}, removed=${changes.filter((c) => c.kind === 'removed').length})\n`);
-  if (!flags['no-open']) openInBrowser(indexPath);
-  return 0;
+function groupDiffDirsByBatch({ projectRoot, plansRoot }) {
+  const groups = new Map();
+  for (const diffDir of walkArchitectureDiffDirs(plansRoot)) {
+    const specDir = path.dirname(diffDir);
+    const batchRoot = findBatchRoot(specDir, plansRoot);
+    const isBatchMember = Boolean(batchRoot && batchRoot !== specDir);
+    const key = isBatchMember ? batchRoot : specDir;
+    if (!groups.has(key)) {
+      groups.set(key, {
+        kind: isBatchMember ? 'batch' : 'single',
+        key,
+        label: path.relative(projectRoot, key),
+        specDir: isBatchMember ? null : specDir,
+        members: [],
+      });
+    }
+    groups.get(key).members.push({ specDir, diffDir, label: path.relative(projectRoot, specDir) });
+  }
+  return [...groups.values()]
+    .map((group) => ({ ...group, members: group.members.sort((a, b) => a.specDir.localeCompare(b.specDir)) }))
+    .sort((a, b) => a.key.localeCompare(b.key));
+}
+
+function findBatchRoot(specDir, plansRoot) {
+  const absolutePlansRoot = path.resolve(plansRoot);
+  let current = path.resolve(path.dirname(specDir));
+  while (current.startsWith(`${absolutePlansRoot}${path.sep}`) || current === absolutePlansRoot) {
+    if (fs.existsSync(path.join(current, COORDINATION_FILE))) return current;
+    if (current === absolutePlansRoot) break;
+    current = path.dirname(current);
+  }
+  return null;
+}
+
+function collectSingleSpecChanges({ projectRoot, specDir, specLabel }) {
+  const overlayDir = path.join(specDir, DIFF_DIRNAME, ATLAS_DIRNAME);
+  if (!hasOverlayState(overlayDir)) {
+    return collectHtmlManifestChanges({ projectRoot, diffDir: path.join(specDir, DIFF_DIRNAME), specLabel });
+  }
+  const base = stateLib.load(baseAtlasDir(projectRoot));
+  const overlay = stateLib.loadOverlay(overlayDir);
+  const merged = stateLib.mergeOverlay(base, overlay);
+  const diff = stateLib.diffPages(base, merged);
+  return diffToChanges({
+    projectRoot,
+    specLabel,
+    htmlRoot: path.join(specDir, DIFF_DIRNAME),
+    diff,
+  });
+}
+
+function hasOverlayState(overlayDir) {
+  return fs.existsSync(path.join(overlayDir, stateLib.INDEX_FILE))
+    || fs.existsSync(path.join(overlayDir, stateLib.FEATURES_DIR))
+    || fs.existsSync(path.join(overlayDir, stateLib.REMOVED_FILE));
+}
+
+async function collectBatchGroupChanges({ projectRoot, outDir, group }) {
+  const batchRootOverlayDir = path.join(group.key, DIFF_DIRNAME, ATLAS_DIRNAME);
+  if (hasOverlayState(batchRootOverlayDir)) {
+    return collectSingleSpecChanges({ projectRoot, specDir: group.key, specLabel: group.label });
+  }
+
+  const memberOverlayDirs = group.members.map((member) => ({
+    ...member,
+    overlayDir: path.join(member.specDir, DIFF_DIRNAME, ATLAS_DIRNAME),
+  }));
+  if (memberOverlayDirs.some((member) => !hasOverlayState(member.overlayDir))) {
+    return group.members.flatMap((member) => (
+      collectSingleSpecChanges({ projectRoot, specDir: member.specDir, specLabel: member.label })
+    ));
+  }
+
+  const base = stateLib.load(baseAtlasDir(projectRoot));
+  let merged = JSON.parse(JSON.stringify(base));
+  for (const member of memberOverlayDirs) {
+    const overlay = stateLib.loadOverlay(member.overlayDir);
+    merged = stateLib.mergeOverlay(merged, overlay);
+  }
+  const diff = stateLib.diffPages(base, merged);
+  const htmlRoot = path.join(outDir, '_batch', group.label);
+  await renderLib.renderAll({
+    outDir: htmlRoot,
+    state: merged,
+    scope: renderLib.scopeFromDiff(diff),
+    removedPaths: renderLib.removedPagePathsFromDiff(diff),
+  });
+  return diffToChanges({
+    projectRoot,
+    specLabel: group.label,
+    htmlRoot,
+    diff,
+  });
+}
+
+function diffToChanges({ projectRoot, specLabel, htmlRoot, diff }) {
+  const resourcesRoot = path.join(projectRoot, ATLAS_REL);
+  const changes = [];
+  const add = (kind, rel) => {
+    const beforeAbs = path.join(resourcesRoot, rel);
+    const afterAbs = kind === 'removed' ? null : path.join(htmlRoot, rel);
+    if (kind === 'removed' && !fs.existsSync(beforeAbs)) return;
+    changes.push({
+      kind,
+      rel,
+      spec: specLabel,
+      beforePath: kind === 'added' ? null : path.relative(projectRoot, beforeAbs),
+      afterPath: afterAbs ? path.relative(projectRoot, afterAbs) : null,
+    });
+  };
+
+  if (diff.macroChanged) {
+    add('modified', renderLib.pagePathFor('macro'));
+  }
+  for (const slug of diff.modifiedFeatures || []) {
+    add('modified', renderLib.pagePathFor('feature', { featureSlug: slug }));
+  }
+  for (const slug of diff.addedFeatures || []) {
+    add('added', renderLib.pagePathFor('feature', { featureSlug: slug }));
+  }
+  for (const item of diff.modifiedSubmodules || []) {
+    add('modified', renderLib.pagePathFor('submodule', { featureSlug: item.feature, submoduleSlug: item.submodule }));
+  }
+  for (const item of diff.addedSubmodules || []) {
+    add('added', renderLib.pagePathFor('submodule', { featureSlug: item.feature, submoduleSlug: item.submodule }));
+  }
+  for (const slug of diff.removedFeatures || []) {
+    add('removed', renderLib.pagePathFor('feature', { featureSlug: slug }));
+  }
+  for (const item of diff.removedSubmodules || []) {
+    add('removed', renderLib.pagePathFor('submodule', { featureSlug: item.feature, submoduleSlug: item.submodule }));
+  }
+
+  return changes;
+}
+
+function collectHtmlManifestChanges({ projectRoot, diffDir, specLabel }) {
+  const resourcesRoot = path.join(projectRoot, ATLAS_REL);
+  const changes = [];
+  for (const after of walkAfterStateHtml(diffDir)) {
+    const beforeAbs = path.join(resourcesRoot, after.rel);
+    const beforeExists = fs.existsSync(beforeAbs);
+    changes.push({
+      kind: beforeExists ? 'modified' : 'added',
+      rel: after.rel,
+      spec: specLabel,
+      beforePath: beforeExists ? path.relative(projectRoot, beforeAbs) : null,
+      afterPath: path.relative(projectRoot, after.abs),
+    });
+  }
+  for (const removedRel of readRemovedManifest(diffDir)) {
+    const beforeAbs = path.join(resourcesRoot, removedRel);
+    if (!fs.existsSync(beforeAbs)) continue;
+    changes.push({
+      kind: 'removed',
+      rel: removedRel,
+      spec: specLabel,
+      beforePath: path.relative(projectRoot, beforeAbs),
+      afterPath: null,
+    });
+  }
+  return changes;
 }
 
 function walkArchitectureDiffDirs(plansRoot) {
@@ -1021,6 +1137,7 @@ module.exports = {
   specOverlayDir,
   runRender,
   walkArchitectureDiffDirs,
+  collectDiffChanges,
   walkAfterStateHtml,
   readRemovedManifest,
   renderDiffViewer,

package/init-project-html/lib/atlas/render.js

@@ -560,11 +560,40 @@ async function renderAll({ outDir, state, scope = null, removedPaths = [] }) {
   // do not linger with the previous (broken) markup or styling.
   if (!scope) {
     sweepOrphanFeaturePages(outDir, state);
+  } else {
+    sweepScopedHtml(outDir, new Set(written.map((file) => file.split(path.sep).join('/'))));
   }
 
   return { written, layout };
 }
 
+function sweepScopedHtml(outDir, keepPaths) {
+  function recurse(dir) {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_e) { return; }
+    for (const entry of entries) {
+      if (entry.name === 'assets' || entry.name === 'atlas' || entry.name.startsWith('.')) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        recurse(full);
+        let remaining;
+        try { remaining = fs.readdirSync(full); } catch (_e) { remaining = null; }
+        if (remaining && remaining.length === 0) {
+          fs.rmSync(full, { recursive: true, force: true });
+        }
+        continue;
+      }
+      if (!entry.isFile() || !entry.name.toLowerCase().endsWith('.html')) continue;
+      const rel = path.relative(outDir, full).split(path.sep).join('/');
+      if (!keepPaths.has(rel)) {
+        fs.rmSync(full, { force: true });
+      }
+    }
+  }
+
+  recurse(outDir);
+}
+
 function sweepOrphanFeaturePages(outDir, state) {
   const featuresRoot = path.join(outDir, 'features');
   if (!fs.existsSync(featuresRoot)) return;

package/init-project-html/lib/atlas/state.js

@@ -26,6 +26,7 @@ const REMOVED_FILE = '_removed.yaml';
 const FEATURES_DIR = 'features';
 const HISTORY_FILE = 'atlas.history.log';
 const UNDO_FILE = 'atlas.history.undo.json';
+const UNDO_STACK_FILE = 'atlas.history.undo.stack.json';
 const ATLAS_DIRNAME = 'atlas';
 
 function readYaml(file) {
@@ -257,6 +258,51 @@ function mergeOverlay(base, overlay) {
   return merged;
 }
 
+function deriveOverlay(base, merged) {
+  const overlay = {
+    meta: null,
+    actors: null,
+    edges: null,
+    featureOrder: null,
+    features: {},
+    removed: { features: [], submodules: [] },
+  };
+
+  if (JSON.stringify(merged.meta || {}) !== JSON.stringify(base.meta || {})) {
+    overlay.meta = merged.meta || {};
+  }
+  if (JSON.stringify(merged.actors || []) !== JSON.stringify(base.actors || [])) {
+    overlay.actors = merged.actors || [];
+  }
+  if (JSON.stringify(merged.edges || []) !== JSON.stringify(base.edges || [])) {
+    overlay.edges = merged.edges || [];
+  }
+
+  const baseOrder = (base.features || []).map((feature) => feature.slug);
+  const mergedOrder = (merged.features || []).map((feature) => feature.slug);
+  if (JSON.stringify(mergedOrder) !== JSON.stringify(baseOrder)) {
+    overlay.featureOrder = mergedOrder;
+  }
+
+  const baseFeatures = new Map((base.features || []).map((feature) => [feature.slug, feature]));
+  const mergedFeatures = new Map((merged.features || []).map((feature) => [feature.slug, feature]));
+
+  for (const [slug, feature] of mergedFeatures) {
+    const baseFeature = baseFeatures.get(slug);
+    if (!baseFeature || JSON.stringify(feature) !== JSON.stringify(baseFeature)) {
+      overlay.features[slug] = feature;
+    }
+  }
+
+  for (const slug of baseFeatures.keys()) {
+    if (!mergedFeatures.has(slug)) {
+      overlay.removed.features.push(slug);
+    }
+  }
+
+  return overlay;
+}
+
 // diffPages compares the merged after-state against the base and
 // classifies which HTML pages must be regenerated (modified) versus
 // emitted fresh (added) versus listed in _removed.txt (removed).
@@ -361,19 +407,52 @@ function appendHistory(atlasDir, entry) {
 }
 
 function writeUndoSnapshot(atlasDir, state) {
-  fs.mkdirSync(atlasDir, { recursive: true });
-  fs.writeFileSync(path.join(atlasDir, UNDO_FILE), JSON.stringify(state, null, 2), 'utf8');
+  const stack = readUndoStack(atlasDir);
+  stack.push(state);
+  writeUndoStack(atlasDir, stack);
 }
 
 function readUndoSnapshot(atlasDir) {
-  const file = path.join(atlasDir, UNDO_FILE);
-  if (!fs.existsSync(file)) return null;
-  return JSON.parse(fs.readFileSync(file, 'utf8'));
+  const stack = readUndoStack(atlasDir);
+  return stack.length > 0 ? stack[stack.length - 1] : null;
 }
 
 function clearUndoSnapshot(atlasDir) {
-  const file = path.join(atlasDir, UNDO_FILE);
-  if (fs.existsSync(file)) fs.rmSync(file);
+  writeUndoStack(atlasDir, []);
+}
+
+function consumeUndoSnapshot(atlasDir, steps = 1) {
+  if (!Number.isInteger(steps) || steps < 1) return null;
+  const stack = readUndoStack(atlasDir);
+  if (stack.length < steps) return null;
+  const snapshot = stack[stack.length - steps];
+  writeUndoStack(atlasDir, stack.slice(0, stack.length - steps));
+  return snapshot;
+}
+
+function readUndoStack(atlasDir) {
+  const stackFile = path.join(atlasDir, UNDO_STACK_FILE);
+  if (fs.existsSync(stackFile)) {
+    return JSON.parse(fs.readFileSync(stackFile, 'utf8'));
+  }
+  const latestFile = path.join(atlasDir, UNDO_FILE);
+  if (fs.existsSync(latestFile)) {
+    return [JSON.parse(fs.readFileSync(latestFile, 'utf8'))];
+  }
+  return [];
+}
+
+function writeUndoStack(atlasDir, stack) {
+  const stackFile = path.join(atlasDir, UNDO_STACK_FILE);
+  const latestFile = path.join(atlasDir, UNDO_FILE);
+  if (!stack || stack.length === 0) {
+    if (fs.existsSync(stackFile)) fs.rmSync(stackFile);
+    if (fs.existsSync(latestFile)) fs.rmSync(latestFile);
+    return;
+  }
+  fs.mkdirSync(atlasDir, { recursive: true });
+  fs.writeFileSync(stackFile, JSON.stringify(stack, null, 2), 'utf8');
+  fs.writeFileSync(latestFile, JSON.stringify(stack[stack.length - 1], null, 2), 'utf8');
 }
 
 module.exports = {
@@ -383,6 +462,7 @@ module.exports = {
   FEATURES_DIR,
   HISTORY_FILE,
   UNDO_FILE,
+  UNDO_STACK_FILE,
   readYaml,
   writeYaml,
   load,
@@ -390,6 +470,7 @@ module.exports = {
   loadOverlay,
   saveOverlay,
   mergeOverlay,
+  deriveOverlay,
   diffPages,
   normalizeFeature,
   normalizeSubmodule,
@@ -397,6 +478,7 @@ module.exports = {
   writeUndoSnapshot,
   readUndoSnapshot,
   clearUndoSnapshot,
+  consumeUndoSnapshot,
   macroVisualOf,
   featureVisualOf,
 };

package/init-project-html/scripts/architecture.js

@@ -43,12 +43,12 @@ Usage:
                                               Manage component rows and edges
   apltk architecture meta set                 Update meta.title / meta.summary
   apltk architecture actor add|remove         Manage top-level actors
-  apltk architecture undo                     Revert the most recent mutation
+  apltk architecture undo [--steps <n>]      Revert the most recent mutation or roll back multiple steps
   apltk architecture --help                   Show this help
 
 Global flags:
   --project <root>   Project root (default: nearest ancestor with resources/project-architecture/, else cwd); missing layout dirs are created when needed
-  --spec <spec_dir>  Mutations write to <spec_dir>/architecture_diff/atlas/
+  --spec <spec_dir>  Single specs write locally; batch member paths write to the coordination.md root architecture_diff/atlas/
   --no-render        Skip auto-render after a mutation
   --no-open          For open/diff: skip launching the browser
   --out <dir>        For diff: override viewer output directory
@@ -255,21 +255,14 @@ function runDiff(opts, io) {
   if (!projectRoot) {
     projectRoot = process.cwd();
   }
-  fs.mkdirSync(path.join(projectRoot, RESOURCES_REL), { recursive: true });
-  const outDir = opts.out || path.join(projectRoot, DEFAULT_OUT_REL);
-  fs.mkdirSync(outDir, { recursive: true });
-
-  const changes = collectChanges(projectRoot);
-  const html = renderViewer({ changes, projectRoot, outDir });
-  const indexPath = path.join(outDir, 'index.html');
-  fs.writeFileSync(indexPath, html, 'utf8');
-
-  io.stdout.write(`${indexPath}\n`);
-  io.stdout.write(
-    `Diff pages: ${changes.length} (modified=${changes.filter((c) => c.kind === 'modified').length}, added=${changes.filter((c) => c.kind === 'added').length}, removed=${changes.filter((c) => c.kind === 'removed').length})\n`,
-  );
-  if (opts.open) openInBrowser(indexPath);
-  return 0;
+  const bootstrap = path.join(__dirname, 'architecture-bootstrap-render.js');
+  const args = [bootstrap, 'diff', '--project', projectRoot];
+  if (opts.out) args.push('--out', opts.out);
+  if (!opts.open) args.push('--no-open');
+  const result = spawnSync(process.execPath, args, { encoding: 'utf8' });
+  if (result.stdout) io.stdout.write(result.stdout);
+  if (result.stderr) io.stderr.write(result.stderr);
+  return result.status || 0;
 }
 
 // main(argv, io) is sync and supports the legacy verbs `open` and

package/optimise-skill/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: optimise-skill
+description: Use prompt engineering to optimise agent skill. Use it when you need to optimise a `SKILL.md`
+---
+
+## 目標
+在不影響被優化技能整體流程前提下，利用提示詞工程，對技能進行優化，減少冗余表達，增強agent對技能的理解能力以及實際工作中的使用效率。
+
+## 驗收條件
+- 被優化技能的最終交付產物不受影響
+- 被優化技能有顯著冗余削減，且具備精確提示能力，盡最大可能釋放LLM的性能
+
+## 工作流程
+
+1. 識別交付物
+完整閱讀整個技能的`SKILL.md`文檔，以及其引用的所有額檔案，包括但不限於`references/`, `scripts/`。基於獲取到的技能上下文資訊，總結出該技能的最終交付產物。
+
+2. 制定驗收條件
+制定驗收條件，從而確保LLM能夠穩定、可復現地按照驗收條件產出符合要求高質量最終交付物
+
+3. 重寫技能
+將整個技能的`SKILL.md`重寫。重寫後的技能應該只包含以下幾個關鍵組成部分：
+- 技能目標
+- 技能驗收條件
+- 技能工作流程
+- 技能使用範例
+- 技能參考資料索引
+對於技能有幫助的內但不符合上述技能架構規範，則應該被分類放置在`references/`下的markdown檔案。
+
+## 範例
+- "一個專注在提示LLM agent進行自我迭代，並為代碼庫帶來性能優化的技能需要被優化"-> "定義驗收條件為優化後性能相較優化前至少提升X個百分比，並且項目之中不存在任何O(n^2)級別時間複雜度的函式和邏輯，並按照標準架構重寫技能。"
+- "一個有大量前端開發範例被包含在`SKILL.md`之中的前端開發技能需要被優化" -> "定義驗收條件為前端頁面`reference`之中提供的大量建議範例重寫且不包含任何建議示例之中明確拒絕的設計，然後按照技能優化流程對技能進行全面的重寫。"
+
+## 參考資料
+- `references/example_skill.md` - 優化後的技能範例

package/optimise-skill/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Optimise Skill"
+  short_description: "Rewrite a SKILL.md into a leaner, higher-signal prompt"
+  default_prompt: "Use $optimise-skill to read the target skill and its supporting files, derive the intended deliverable plus acceptance criteria, then rewrite the skill into a tighter goal / acceptance criteria / workflow / examples / references structure without changing the final outcome."

package/optimise-skill/references/example_skill.md

@@ -0,0 +1,35 @@
+---
+name: optimise-skill
+description: Use prompt engineering to optimise agent skill. Use it when you need to optimise a `SKILL.md`
+---
+
+## 目標
+在不影響被優化技能整體流程前提下，利用提示詞工程，對技能進行優化，減少冗余表達，增強agent對技能的理解能力以及實際工作中的使用效率。
+
+## 驗收條件
+- 被優化技能的最終交付產物不受影響
+- 被優化技能有顯著冗余削減，且具備精確提示能力，盡最大可能釋放LLM的性能
+
+## 工作流程
+
+1. 識別交付物
+完整閱讀整個技能的`SKILL.md`文檔，以及其引用的所有額檔案，包括但不限於`references/`, `scripts/`。基於獲取到的技能上下文資訊，總結出該技能的最終交付產物。
+
+2. 制定驗收條件
+制定驗收條件，從而確保LLM能夠穩定、可復現地按照驗收條件產出符合要求高質量最終交付物
+
+3. 重寫技能
+將整個技能的`SKILL.md`重寫。重寫後的技能應該只包含以下幾個關鍵組成部分：
+- 技能目標
+- 技能驗收條件
+- 技能工作流程
+- 技能使用範例
+- 技能參考資料索引
+對於技能有幫助的內但不符合上述技能架構規範，則應該被分類放置在`references/`下的markdown檔案。
+
+## 範例
+- "一個專注在提示LLM agent進行自我迭代，並為代碼庫帶來性能優化的技能需要被優化"-> "定義驗收條件為優化後性能相較優化前至少提升X個百分比，並且項目之中不存在任何O(n^2)級別時間複雜度的函式和邏輯，並按照標準架構重寫技能。"
+- "一個有大量前端開發範例被包含在`SKILL.md`之中的前端開發技能需要被優化" -> "定義驗收條件為前端頁面`reference`之中提供的大量建議範例重寫且不包含任何建議示例之中明確拒絕的設計，然後按照技能優化流程對技能進行全面的重寫。"
+
+## 參考資料
+- `references/example_skill.md` - 優化後的技能範例

package/package.json

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

package/spec-to-project-html/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: spec-to-project-html
 description: >-
-  Sync the project HTML architecture atlas to active planning specs by driving `apltk architecture --spec <spec_dir>`. The CLI writes overlay YAML under `<spec_dir>/architecture_diff/atlas/` and re-renders only the affected proposed-after HTML pages — macro SVG and per-sub-module internal-dataflow diagrams stay zoomable like the base atlas — so `apltk architecture diff` pairs before/after by path under `docs/plans/**/architecture_diff/`. Preserve the two-layer rule and the responsibility split: **subagents only** — each subagent reads ONE affected feature and declares EVERY intra-feature overlay change; the main agent **waits until all subagents finish**, then aggregates outbound summaries and declares **only** cross-feature edges. **Exact CLI spelling:** always `apltk architecture --help`. Ground every declaration in repo evidence; mark `TBD` when code is missing.
+  Sync the project HTML architecture atlas to active planning specs by driving `apltk architecture --spec <spec_dir>`. Single specs write overlay YAML under `<spec_dir>/architecture_diff/atlas/`; batch member paths resolve to the shared batch-root `architecture_diff/` beside `coordination.md`. The CLI re-renders only the affected proposed-after HTML pages — macro SVG and per-sub-module internal-dataflow diagrams stay zoomable like the base atlas — so `apltk architecture diff` pairs before/after by path under `docs/plans/**/architecture_diff/`. Preserve the two-layer rule and the responsibility split: **subagents only** — each subagent reads ONE affected feature and declares EVERY intra-feature overlay change; the main agent **waits until all subagents finish**, then aggregates outbound summaries and declares **only** cross-feature edges. **Exact CLI spelling:** always `apltk architecture --help`. Ground every declaration in repo evidence; mark `TBD` when code is missing.
 ---
 
 # Spec To Project HTML
@@ -17,7 +17,7 @@ description: >-
 ## Non-negotiables
 
 - **MUST** read specs in order unless the user directs otherwise: `spec.md` → `design.md` → `contract.md` → coordination notes.
-- **MUST** declare every change through the CLI with `--spec <spec_dir>` (exact verbs/flags: **`apltk architecture --help`**). The CLI writes overlay YAML to `<spec_dir>/architecture_diff/atlas/` and re-renders only the affected proposed-after HTML pages there. **MUST NOT** hand-edit `architecture_diff/**/*.html` — the renderer owns those files.
+- **MUST** declare every change through the CLI with `--spec <spec_dir>` (exact verbs/flags: **`apltk architecture --help`**). Single specs write overlay YAML to `<spec_dir>/architecture_diff/atlas/` and re-render only the affected proposed-after HTML pages there. Batch member paths resolve to the shared batch-root `architecture_diff/` beside `coordination.md`, so the whole batch keeps one overlay and one rendered diff. **MUST NOT** hand-edit `architecture_diff/**/*.html` — the renderer owns those files.
 - **MUST** obey the semantic rules from `init-project-html/SKILL.md`:
   - Sub-module pages stay self-only — express cross-boundary interactions via **edges** (cross-feature or intra-feature), never as sub-module page prose.
   - Feature pages stay lightweight — cross-sub-module choreography belongs in **edges**, not in `dataflow` prose that pretends to cross features.
@@ -38,7 +38,7 @@ description: >-
 - **Evidence**: cite the spec passage (design subsystem entry) alongside the code path; record the citation in `meta.summary` or in sub-module purposes when relevant.
 - **Execution**: locate the plan set → list affected feature modules → subagent fan-out → **all complete** → cross-feature edges → `render --spec` if batched → `validate --spec` → `diff` check → handover.
 - **Quality**: macro overlay still shows every cross-feature data-row the spec requires; sub-module declarations stay self-only; `apltk architecture diff` opens cleanly with no orphan pages; no dangling edges.
-- **Output**: touches only `<spec_dir>/architecture_diff/atlas/**` (overlay state) and `<spec_dir>/architecture_diff/**/*.html` (renderer output). Base `resources/project-architecture/` is **NEVER** mutated.
+- **Output**: single specs touch only `<spec_dir>/architecture_diff/atlas/**` (overlay state) and `<spec_dir>/architecture_diff/**/*.html` (renderer output); batch specs write the same artifacts under the batch root beside `coordination.md`. Base `resources/project-architecture/` is **NEVER** mutated.
 
 ## Acceptance criteria (mirrors `init-project-html`)
 
@@ -92,7 +92,7 @@ List overlay files touched (or verb families used), the diff counts (`modified`
 
 ## Sample hints
 
-- **Batch merge**: each member spec’s `--spec <member_dir>` writes its own overlay; `diff` lists each spec’s section in the paginated viewer.
+- **Batch merge**: each member spec still calls `--spec <member_dir>`, but the CLI resolves writes to the shared batch-root overlay beside `coordination.md`; `diff` shows the batch as one combined architecture delta.
 - **Spec shrinks scope**: prefer `submodule set --role "deprecated: ..."` before `submodule remove` so reviewers see intent.
 - **Design-only change**: still review edges — order shifts surface as edge mutations; `validate --spec` catches dangling references.
 

package/spec-to-project-html/agents/openai.yaml

@@ -3,7 +3,7 @@ interface:
   short_description: "Sync the project HTML architecture atlas with active planning specs via `apltk architecture --spec`"
   default_prompt: >-
     Use $spec-to-project-html. Read docs/plans (spec → design → contract). Every overlay mutation: `apltk architecture --spec <spec_dir> …`. **Exact commands: `apltk architecture --help`** — do not trust long command lists in docs.
-    CLI writes `<spec_dir>/architecture_diff/atlas/*.yaml` + affected HTML under `<spec_dir>/architecture_diff/`. Base `resources/project-architecture/` is read-only here. NEVER hand-edit `architecture_diff/**`.
+    Single specs write `<spec_dir>/architecture_diff/atlas/*.yaml` + affected HTML under `<spec_dir>/architecture_diff/`. Batch member paths resolve to the shared batch-root `architecture_diff/` beside `coordination.md`, so one batch keeps one overlay + one rendered diff. Base `resources/project-architecture/` is read-only here. NEVER hand-edit `architecture_diff/**`.
     **`apltk architecture diff`** builds a paginated viewer: scans all `docs/plans/**/architecture_diff/`, pairs overlay paths with base atlas HTML by relative path, labels modified/added/removed — use it to verify the architecture delta before hand-off.
     **Subagents only:** dispatch ONE write-capable subagent per AFFECTED feature; each applies ALL intra-feature overlay mutations (`submodule`/`function`/`variable`/`dataflow`/`error`/`edge` within that feature). Each returns ONLY change summary + outbound boundary deltas for OTHER features.
     **HARD GATE:** main agent MUST wait until ALL subagents finish before ANY cross-feature `edge add|remove`, overlay `meta` that stitches multiple features, or shared `actor` for cross-feature context. Then `render --spec`, `validate --spec`.