refresh-kb-links

name	refresh-kb-links
description	Refresh Forge KB and workflow links in agent instruction files (CLAUDE.md, AGENTS.md, etc.)

forge:refresh-kb-links

Scan every coding-agent instruction file in the project and ensure each has up-to-date links to the Forge knowledge base and generated workflow entry points. This skill is invoked by /forge:refresh-kb-links or conversationally via /forge:ask.

Setup

Read the Forge config to determine the KB root path:

KB_PATH: !`node -e "try{console.log(require('./.forge/config.json').paths.engineering)}catch{console.log('engineering')}"`

Known Agent Instruction Files

Detect which of these files exist in the project root:

File	Coding tool
CLAUDE.md	Claude Code
AGENTS.md	OpenAI Codex / generic
AGENT.md	generic
.github/copilot-instructions.md	GitHub Copilot
.cursorrules	Cursor (legacy)
.cursor/rules/*.mdc	Cursor (current)
GEMINI.md	Google Gemini

For each file found, check whether it already contains managed Forge sections.

Managed Section Markers

Each file may have two independent managed sections:

KB links section

Open marker (prefix match — tolerates minor text variations):

<!-- forge-kb-links

Close marker (exact):

<!-- /forge-kb-links -->

Workflow links section

Open marker (prefix match):

<!-- forge-workflow-links

Close marker (exact):

<!-- /forge-workflow-links -->

Content Rules

KB section content

Only include rows for files that actually exist on disk:

• {KB_PATH}/MASTER_INDEX.md → "All sprints, tasks, bugs, and features"
• {KB_PATH}/architecture/INDEX.md → "Stack, processes, database, routing, deployment"
• {KB_PATH}/business-domain/INDEX.md → "Entity model and domain concepts"

<!-- forge-kb-links: managed by Forge — do not edit manually -->
## Forge Knowledge Base

| Index | Contents |
|-------|----------|
| [MASTER_INDEX]({KB_PATH}/MASTER_INDEX.md) | All sprints, tasks, bugs, and features |
| [Architecture]({KB_PATH}/architecture/INDEX.md) | Stack, processes, database, routing, deployment |
| [Business Domain]({KB_PATH}/business-domain/INDEX.md) | Entity model and domain concepts |

Personas live in `.forge/personas/`.
<!-- /forge-kb-links -->

Workflow section content

Only include rows for workflow files that actually exist on disk. Check each:

• .forge/workflows/plan_task.md → "Research codebase → implementation plan"
• .forge/workflows/implement_plan.md → "Execute approved plan → code changes"
• .forge/workflows/fix_bug.md → "Triage → fix → verify"
• .forge/workflows/orchestrate_task.md → "Full task pipeline (plan → implement → review → commit)"
• .forge/workflows/run_sprint.md → "Full sprint orchestration"
• .forge/workflows/architect_sprint_plan.md → "Sprint planning and task decomposition"
• .forge/workflows/architect_sprint_intake.md → "Sprint intake and requirements elicitation"

<!-- forge-workflow-links: managed by Forge — do not edit manually -->
## Forge Workflows

| Workflow | Purpose |
|----------|---------|
| [Plan](.forge/workflows/plan_task.md) | Research codebase → implementation plan |
| [Implement](.forge/workflows/implement_plan.md) | Execute approved plan → code changes |
| [Fix bug](.forge/workflows/fix_bug.md) | Triage → fix → verify |
| [Run task](.forge/workflows/orchestrate_task.md) | Full task pipeline (plan → implement → review → commit) |
| [Run sprint](.forge/workflows/run_sprint.md) | Full sprint orchestration |
<!-- /forge-workflow-links -->

(Only include rows where the referenced .forge/workflows/ file exists on disk.)

KB Integrity Check

Before scanning agent instruction files, verify that the knowledge graph itself is complete. The collate tool generates INDEX.md files at every node of the graph; if they are missing, links in MASTER_INDEX.md are broken and agents navigate to dead ends.

Check the following, using KB_PATH as the root:

1. Sprint INDEX files — for every directory under {KB_PATH}/sprints/, check that {KB_PATH}/sprints/{sprint-dir}/INDEX.md exists.

2. Task INDEX files — for every subdirectory under {KB_PATH}/sprints/{sprint-dir}/ that looks like a task folder (contains at least one .md file), check that its INDEX.md exists.

3. Bug INDEX files — for every directory under {KB_PATH}/bugs/, check that {KB_PATH}/bugs/{bug-dir}/INDEX.md exists.

If any INDEX files are missing, prepend this warning to the output (before the agent-file approval prompt):

⚠️  KB knowledge graph has broken links — INDEX.md files are missing:

  △ {KB_PATH}/sprints/PROJ-S01/INDEX.md         — missing
  △ {KB_PATH}/sprints/PROJ-S01/PROJ-S01-T01/INDEX.md — missing
  △ {KB_PATH}/bugs/PROJ-B01-some-bug/INDEX.md   — missing

Run collate to regenerate them:
  node "$FORGE_ROOT/tools/collate.cjs"

If all INDEX files are present (or there are no sprint/task/bug folders yet), skip this block entirely. Do not warn when the KB is intact.

Staleness Check

For each detected agent instruction file, check both sections:

1. If the section marker is absent → section is missing
2. If the section markers are present → extract the current content between them. Compare current content vs. the content you would write (with current KB_PATH and only existing files). If they differ → section is stale. If identical → current.

Approval Prompt

After scanning all files, present a single consolidated approval prompt:

🏮 forge:refresh-kb-links — KB & Workflow Visibility

Forge has generated a knowledge base and SDLC workflows for this project. Without links
to these in your agent instruction files, every new conversation starts blind — no KB
context, no workflow playbook.

Found agent instruction files:
  〇 CLAUDE.md        — no Forge KB links, no workflow links
  〇 AGENTS.md        — no Forge KB links, no workflow links

Add ## Forge Knowledge Base and ## Forge Workflows sections to each? [Y/n]
(or choose individually: [c])

Adapt the status lines to reflect the actual state:

• 〇 {filename} — no Forge KB links, no workflow links (both missing)
• 〇 {filename} — KB links stale (KB section present but stale)
• 〇 {filename} — workflow links stale (workflow section present but stale)
• 〇 {filename} — KB links stale, workflow links stale (both stale)
• 〇 {filename} — links current, no changes needed (both present and current — skip)

If all detected files already have current links: output:

🏮 forge:refresh-kb-links — all KB and workflow links are current. No changes needed.

And return without prompting.

Writing Sections

On approval ([Y] or per-file confirm):

• Missing section: append the section to the end of the file.
• Stale section: replace content between the open and close markers with fresh content. Preserve everything outside the markers exactly.

Write the {KB_PATH} substitution with the actual resolved path value (not the literal string {KB_PATH}). The resulting markdown should have real paths like engineering/MASTER_INDEX.md or ai-docs/MASTER_INDEX.md.

Idempotency

On a second run where all links are already current, output the "all links current" message and return immediately. Do not re-write unchanged sections.

Rename Instructions

If the user later renames the KB folder:

1. Rename the folder on disk.
2. Run: node "$FORGE_ROOT/tools/manage-config.cjs" set paths.engineering <new-name>
3. Re-run forge:refresh-kb-links to refresh the links in all agent instruction files.