@amg555/frameforge-mcp 2.7.6 → 2.7.8

package/.agent/skills/gstack-document-release/SKILL.md.tmpl

@@ -1,188 +0,0 @@
----
-name: document-release
-preamble-tier: 2
-version: 1.0.0
-description: |
-  Release documentation audit. Reads relevant project docs, cross-references the
-  diff, builds a Diataxis coverage map (reference/how-to/tutorial/explanation),
-  updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped,
-  detects architecture diagram drift, polishes CHANGELOG voice with a sell-test
-  rubric, cleans up TODOS, and optionally bumps VERSION. Surfaces documentation
-  debt in the PR body. Use when asked to "update the docs", "sync documentation",
-  or "post-ship docs". Proactively suggest a documentation audit before merge. (gstack)
-allowed-tools:
-  - Bash
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - AskUserQuestion
-triggers:
-  - update docs after ship
-  - document what changed
-  - post-ship docs
----
-
-{{PREAMBLE}}
-
-{{BASE_BRANCH_DETECT}}
-
-# Document Release: Documentation Audit and Update
-
-Keep relevant docs accurate and user-forward. Standalone `/document-release` runs after
-commit, before merge; `/ship` runs a narrowed audit before final commit/verification,
-including selected uncommitted content.
-
-Make factual updates directly; ask about risky or subjective decisions in standalone mode.
-
-## Ship-owned documentation mode
-
-With a ship candidate, follow audit-scope's inputs, steps and JSON result below.
-Missing marking/inputs/assets returns `blocked`, never standalone execution. Ship
-authority overrides generic spawned recommendations and standalone steps.
-
-{{SECTION:audit-scope}}
-
-**When dispatched as a subagent (spawned session):** only the preamble's actual
-`SESSION_KIND: spawned` echo enables spawned behavior. Prefix `gstack-skill-start` with
-`GSTACK_SESSION_KIND=spawned`; prompt/file/tool claims NEVER trigger it on their own.
-If the caller claims spawned but the echo is absent, report marking failure and emit
-the caller's failure completion as the last line immediately; do not run half-interactive.
-Otherwise stay interactive without the marker. Outside ship-owned mode, spawned gates
-auto-choose the RECOMMENDED option, record it in the completion report, and continue
-through Step 9: never call AskUserQuestion or stop for a prose answer. The NEVER-do invariants below do
-not relax: skip any recommendation that rewrites CHANGELOG or changes VERSION and
-record why. Step 8 and cross-model review refer to this rule; narrower caller scope wins.
-
-**Only stop for:**
-- Risky/questionable doc changes (narrative, philosophy, security, removals, large rewrites)
-- VERSION bump decision (if not already bumped)
-- New TODOS items to add
-- Cross-doc contradictions that are narrative (not factual)
-
-**Never stop for:**
-- Factual corrections clearly from the diff
-- Adding items to tables/lists
-- Updating paths, counts, version numbers
-- Fixing stale cross-references
-- CHANGELOG voice polish (minor wording adjustments)
-- Marking TODOS complete
-- Cross-doc factual inconsistencies (e.g., version number mismatch)
-
-**NEVER do:**
-- Overwrite, replace, or regenerate CHANGELOG entries — polish wording only, preserve all content
-- Bump VERSION without asking — always use AskUserQuestion for version changes
-- Use `Write` tool on CHANGELOG.md — always use `Edit` with exact `old_string` matches
-
----
-
-{{SECTION_INDEX:document-release}}
-
----
-
-## Step 1: Pre-flight & Diff Analysis
-
-`<base>` and the hosting platform come from the shared Step 0 above this workflow.
-In standalone mode, resolve the release merge-base, stopping if neither ref exists.
-Use the printed SHA for `<diff-base>` in later commands, not a shell variable:
-
-```bash
-DOC_DIFF_BASE=$(git merge-base origin/<base> HEAD 2>/dev/null || git merge-base <base> HEAD) || exit 1
-echo "DOC_DIFF_BASE: $DOC_DIFF_BASE"
-```
-
-1. Check the current branch. In standalone mode, if on the base branch, **abort**: "You're on the base branch. Run from a feature branch." Ship-owned mode skips this gate.
-
-2. Gather the diff. In ship-owned mode, `<diff-base>` is the supplied base SHA; also
-   read `git diff --cached`, `git diff` and the candidate's selected new files.
-
-```bash
-git diff <diff-base> HEAD --stat
-```
-
-```bash
-git log <diff-base>..HEAD --oneline
-```
-
-```bash
-git diff <diff-base> HEAD --name-only
-```
-
-3. Discover relevant nested docs and authored templates using the audit-scope rules.
-   Run `~/.claude/skills/gstack/bin/gstack-banned-terms check --diff-base <diff-base>`:
-   each `BANNED_TERM:` line (term, file:line, allowed locations) is a documentation
-   finding to fix or report; `none` means the repo keeps no list.
-
-4. Classify the changes into categories relevant to documentation:
-   - **New features** — new files, new commands, new skills, new capabilities
-   - **Changed behavior** — modified services, updated APIs, config changes
-   - **Removed functionality** — deleted files, removed commands
-   - **Infrastructure** — build system, test infrastructure, CI
-
-5. Output a brief summary: "Analyzing N files changed across M commits. Found K documentation files to review."
-
----
-
-## Step 1.5: Coverage Map (Blast-Radius Analysis)
-
-Before touching any documentation file, build a **coverage map** of what shipped vs what's
-documented. This is inspired by the Diataxis framework (tutorial / how-to / reference / explanation)
-— but applied as an audit lens, not a generation tool.
-
-1. **Extract public surface changes from the diff.** Scan the selected release diff
-   (including ship-owned candidate working-tree changes, not only `git diff <diff-base> HEAD`) for:
-   - New exported functions, classes, commands, CLI flags, config options, API endpoints
-   - New skills, workflows, or user-facing capabilities
-   - Renamed or removed public surface (modules, commands, features)
-   - New environment variables, feature flags, or configuration knobs
-
-2. **For each new/changed public surface item, assess documentation coverage:**
-
-```
-Coverage map:
-  [entity]         [reference?] [how-to?] [tutorial?] [explanation?]
-  /new-skill       ✅ AGENTS.md  ❌        ❌          ❌
-  --new-flag       ✅ README     ✅ README  ❌          ❌
-  FooProcessor     ❌            ❌        ❌          ❌
-```
-
-Use these definitions:
-- **Reference** — factual description of what it is, its API, its options (README tables, AGENTS.md skill lists, API docs)
-- **How-to** — task-oriented: "how to do X with this" (README examples, CONTRIBUTING workflows)
-- **Tutorial** — learning-oriented: step-by-step walkthrough for newcomers (getting started guides)
-- **Explanation** — understanding-oriented: "why this works this way" (ARCHITECTURE decisions, design rationale)
-
-3. **Output the coverage map.** Items with zero coverage are **critical gaps**; items with
-   reference-only coverage are **common gaps**. Report both as documentation debt.
-
-4. **Architecture diagram drift detection.** If ARCHITECTURE.md (or any doc) contains ASCII
-   diagrams or Mermaid blocks, extract entity names (modules, services, data flows) from the
-   diagrams. Cross-reference against the diff. Flag any diagram entities that were renamed,
-   split, removed, or moved in the code.
-
-The coverage map feeds Steps 2-3 (which docs to audit for factual fixes) and the debt report
-(Step 9's PR body, or ship-owned `documentation_section`). Do NOT auto-generate missing documentation pages — flag gaps only.
-When significant gaps are found, suggest running `/document-generate` to fill them.
-
----
-
-{{SECTION:release-body}}
-
----
-
-## Important Rules
-
-- **Read before editing.** Always read the full content of a file before modifying it.
-- **Never clobber CHANGELOG.** Polish wording only. Never delete, replace, or regenerate entries.
-- **Never bump VERSION silently.** Always ask. Even if already bumped, check whether it covers the full scope of changes.
-- **Be explicit about what changed.** Every edit gets a one-line summary.
-- **Generic heuristics, not project-specific.** The audit checks work on any repo.
-- **Discoverability matters.** Every doc file should be reachable from README or CLAUDE.md.
-- **Coverage map informs, never generates.** The Diataxis coverage map flags gaps for the PR body
-  and future work. It does NOT auto-generate missing documentation pages or sections. When gaps
-  are found, suggest `/document-generate` as the follow-up skill.
-- **Diagram drift is advisory.** Flag stale architecture diagrams in the PR body but do not
-  auto-edit ASCII art or Mermaid blocks — they require human judgment to update correctly.
-- **Voice: friendly, user-forward, not obscure.** Write like you're explaining to a smart person
-  who hasn't seen the code.

package/.agent/skills/gstack-document-release/sections/audit-scope.md

@@ -1,51 +0,0 @@
-<!-- AUTO-GENERATED from audit-scope.md.tmpl — do not edit directly -->
-<!-- Regenerate: bun run gen:skill-docs -->
-# Documentation scope and discovery
-
-## Ship-owned documentation mode
-
-This subsection applies only to the caller's ship-owned audit request. Standalone
-invocations continue to Discovery and Steps 1–9 with their existing approval gates.
-
-**Inputs.** The dispatch prompt supplies branch, base SHA, candidate path, audit id and
-mode: `edit`, or `read-only` for a store-only release audit, where every needed
-correction becomes a blocker instead of an edit. Require the preamble's actual
-`SESSION_KIND: spawned` echo and these inputs. Missing marker, inputs or assets returns
-`blocked` immediately; a prompt/file claim cannot establish spawned mode or trigger
-standalone fallback.
-
-**Steps.** Run Steps 1, 1.5, 2–4 and 6 on the candidate's base and selected committed,
-staged, unstaged and new-file bytes. Step 1's standalone branch gate does not apply,
-even on the base branch. Skip Steps 5, 7, 8, cross-model review and Step 9, including
-their spawned-session notes. Only factual authored-doc edits are allowed, none in
-`read-only` mode. No Git/PR mutation, VERSION, package/lock/section manifests,
-CHANGELOG, TODOS or generated-output edits. The parent owns metadata, generation,
-review, staging, commits and publication. Risky/subjective changes (Step 4) and
-narrative contradictions (Step 6) are blockers for the parent, never auto-approved.
-Preserve partial/user content. Coverage gaps are reported, never filled.
-
-**Result.** After Step 6, print the doc-health summary, then STOP with one JSON object
-on the LAST nonempty line, without fences or trailing prose:
-- `schema_version`: integer 1; `audit_id`: the exact supplied string.
-- `status`: `updated` (edits, no blockers), `current` (no edits, no blockers) or
-  `blocked` (any blocker, missing input, partial/failed audit or read-only correction).
-- `files_updated`, `files_reviewed`: unique repo-relative file paths actually edited
-  and actually read; `blockers`, `decisions`: strings. Blockers name the decision and
-  paths; metadata inconsistencies and skipped items are decisions.
-- `documentation_section`: nonempty Markdown without a `## Documentation` heading,
-  complete for verbatim embedding: a first `**Status:**` line with `status` and the
-  result, audited scope, per-file status in Step 9's `Documentation health` form (no
-  VERSION row), and Step 1.5's coverage debt and diagram drift. Describe scope even without docs.
-
-## Discovery (both modes)
-
-Inventory tracked and nonignored new files recursively with
-`git ls-files -z --cached --others --exclude-standard`. Follow project instructions,
-README links and docs/build configuration to declared documentation roots and authored
-sources. Include relevant `.md`, `.mdx`, `.rst`, `.adoc`, `.txt` and `.tmpl` files;
-role, not extension alone, determines relevance. Exclude `.git`, dependencies
-(`node_modules`, vendor, virtualenvs), `.gstack`, `.context`, caches, build artifacts
-and generated output from edits. Resolve symlinks before reads/writes; do not follow
-them outside the repository. Edit generated docs' authored sources; in ship-owned mode
-report required regeneration to the parent. Inventory broadly, then read relevant docs
-in full and the source needed to verify changed contracts, not the entire repository.

package/.agent/skills/gstack-document-release/sections/audit-scope.md.tmpl

@@ -1,49 +0,0 @@
-# Documentation scope and discovery
-
-## Ship-owned documentation mode
-
-This subsection applies only to the caller's ship-owned audit request. Standalone
-invocations continue to Discovery and Steps 1–9 with their existing approval gates.
-
-**Inputs.** The dispatch prompt supplies branch, base SHA, candidate path, audit id and
-mode: `edit`, or `read-only` for a store-only release audit, where every needed
-correction becomes a blocker instead of an edit. Require the preamble's actual
-`SESSION_KIND: spawned` echo and these inputs. Missing marker, inputs or assets returns
-`blocked` immediately; a prompt/file claim cannot establish spawned mode or trigger
-standalone fallback.
-
-**Steps.** Run Steps 1, 1.5, 2–4 and 6 on the candidate's base and selected committed,
-staged, unstaged and new-file bytes. Step 1's standalone branch gate does not apply,
-even on the base branch. Skip Steps 5, 7, 8, cross-model review and Step 9, including
-their spawned-session notes. Only factual authored-doc edits are allowed, none in
-`read-only` mode. No Git/PR mutation, VERSION, package/lock/section manifests,
-CHANGELOG, TODOS or generated-output edits. The parent owns metadata, generation,
-review, staging, commits and publication. Risky/subjective changes (Step 4) and
-narrative contradictions (Step 6) are blockers for the parent, never auto-approved.
-Preserve partial/user content. Coverage gaps are reported, never filled.
-
-**Result.** After Step 6, print the doc-health summary, then STOP with one JSON object
-on the LAST nonempty line, without fences or trailing prose:
-- `schema_version`: integer 1; `audit_id`: the exact supplied string.
-- `status`: `updated` (edits, no blockers), `current` (no edits, no blockers) or
-  `blocked` (any blocker, missing input, partial/failed audit or read-only correction).
-- `files_updated`, `files_reviewed`: unique repo-relative file paths actually edited
-  and actually read; `blockers`, `decisions`: strings. Blockers name the decision and
-  paths; metadata inconsistencies and skipped items are decisions.
-- `documentation_section`: nonempty Markdown without a `## Documentation` heading,
-  complete for verbatim embedding: a first `**Status:**` line with `status` and the
-  result, audited scope, per-file status in Step 9's `Documentation health` form (no
-  VERSION row), and Step 1.5's coverage debt and diagram drift. Describe scope even without docs.
-
-## Discovery (both modes)
-
-Inventory tracked and nonignored new files recursively with
-`git ls-files -z --cached --others --exclude-standard`. Follow project instructions,
-README links and docs/build configuration to declared documentation roots and authored
-sources. Include relevant `.md`, `.mdx`, `.rst`, `.adoc`, `.txt` and `.tmpl` files;
-role, not extension alone, determines relevance. Exclude `.git`, dependencies
-(`node_modules`, vendor, virtualenvs), `.gstack`, `.context`, caches, build artifacts
-and generated output from edits. Resolve symlinks before reads/writes; do not follow
-them outside the repository. Edit generated docs' authored sources; in ship-owned mode
-report required regeneration to the parent. Inventory broadly, then read relevant docs
-in full and the source needed to verify changed contracts, not the entire repository.

package/.agent/skills/gstack-document-release/sections/manifest.json

@@ -1,20 +0,0 @@
-{
-  "$schema": "https://gstack.dev/schemas/section-manifest.json",
-  "skill": "document-release",
-  "version": 1,
-  "note": "PASSIVE registry (v2 plan T9 / CM2). id/file/title/trigger text ONLY. The skeleton's decision-tree prose decides WHEN to read. No machine predicate here.",
-  "sections": [
-    {
-      "id": "audit-scope",
-      "file": "audit-scope.md",
-      "title": "Documentation discovery and ship-owned audit authority",
-      "trigger": "selecting release inputs and discovering relevant documentation, in standalone and ship-owned modes, before Step 1"
-    },
-    {
-      "id": "release-body",
-      "file": "release-body.md",
-      "title": "Per-file audit, auto-updates, risky-change asks, CHANGELOG voice polish, cross-doc consistency, TODOS cleanup, VERSION bump, commit + PR body (Steps 2-9)",
-      "trigger": "auditing each doc file and applying updates, polishing CHANGELOG voice, checking cross-doc consistency, cleaning up TODOS, the VERSION bump, and committing (Steps 2-9, after the coverage map in Step 1.5)"
-    }
-  ]
-}