forgedock 1.0.4 → 1.0.6

package/commands/work-on/build/architect.md

@@ -65,6 +65,134 @@ gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
 
 ---
 
+## Phase A0: Read Custom Instructions and Project Conventions
+
+Read project-resident authoritative docs **before** any code path tracing. `project/custom-instructions.md` has the highest precedence of all knowledge sources — its directives are BINDING and override agent defaults, training knowledge, and all other context. Other applicable `project/*.md` files provide authoritative project conventions the architect must enforce.
+
+**Time budget**: 30 seconds. If exceeded, log a skip note and continue to Phase A1.
+
+**Skip if**: `{REPO_PATH}` is not set, devdocs path does not exist, or path contains no markdown files.
+
+### Step 0: Resolve devdocs path
+
+Read `forge.yaml → devdocs.path` from the project root. Default to `devdocs` if the key is absent or unreadable.
+
+```bash
+DEVDOCS_PATH=""
+
+FORGE_YAML_PATH="{REPO_PATH}/forge.yaml"
+
+if [ -f "$FORGE_YAML_PATH" ]; then
+  DEVDOCS_REL=$(grep -A5 '^devdocs:' "$FORGE_YAML_PATH" \
+    | grep '^\s*path:' \
+    | head -1 \
+    | sed 's/.*path:\s*//' \
+    | tr -d '"'"'"' \
+    | tr -d '[:space:]')
+fi
+
+DEVDOCS_REL="${DEVDOCS_REL:-devdocs}"
+DEVDOCS_PATH="{REPO_PATH}/${DEVDOCS_REL}"
+
+if [ ! -d "$DEVDOCS_PATH" ]; then
+  echo "Devdocs path '${DEVDOCS_PATH}' does not exist — skipping Phase A0 (no blocking)"
+  DEVDOCS_PATH=""
+fi
+```
+
+> **Note**: `devdocs/` must be tracked in git for the worktree to contain it. If the project gitignores `devdocs/`, the path will not exist in the worktree and this phase silently skips — this is by design. Run `git check-ignore -v devdocs/` to confirm tracking status.
+
+### Step 1: Priority read — custom instructions (HIGHEST PRECEDENCE)
+
+Always read `project/custom-instructions.md` first if it exists. Directives in this file are BINDING — they override everything else.
+
+```bash
+CUSTOM_INSTRUCTIONS=""
+
+if [ -n "$DEVDOCS_PATH" ]; then
+  CUSTOM_INSTRUCTIONS_FILE="${DEVDOCS_PATH}/project/custom-instructions.md"
+  if [ -f "$CUSTOM_INSTRUCTIONS_FILE" ]; then
+    TOTAL_LINES=$(wc -l < "$CUSTOM_INSTRUCTIONS_FILE" 2>/dev/null || echo 0)
+    if [ "$TOTAL_LINES" -gt 200 ]; then
+      CUSTOM_INSTRUCTIONS=$(head -200 "$CUSTOM_INSTRUCTIONS_FILE")
+      CUSTOM_INSTRUCTIONS="${CUSTOM_INSTRUCTIONS}
+
+_[Truncated at 200 lines — ${TOTAL_LINES} total. Read full file for complete directives.]_"
+    else
+      CUSTOM_INSTRUCTIONS=$(cat "$CUSTOM_INSTRUCTIONS_FILE")
+    fi
+  fi
+fi
+```
+
+### Step 2: Secondary reads — other applicable project files
+
+Read all other `*.md` files under `DEVDOCS_PATH` where `applies_to` contains `work-on`. Skip `project/custom-instructions.md` (already read). Sort by authority (`required` first).
+
+```bash
+PROJECT_CONVENTIONS=""
+
+if [ -n "$DEVDOCS_PATH" ]; then
+  APPLICABLE_FILES=""
+
+  while IFS= read -r -d '' mdfile; do
+    # Skip custom-instructions — already read as priority
+    [ "$mdfile" = "${DEVDOCS_PATH}/project/custom-instructions.md" ] && continue
+
+    FRONTMATTER=$(awk '/^---/{c++; if(c==1){next} if(c==2){exit}} c==1{print}' "$mdfile" 2>/dev/null)
+
+    if echo "$FRONTMATTER" | grep -q 'applies_to:.*work-on'; then
+      AUTHORITY=$(echo "$FRONTMATTER" | grep 'authority:' | head -1 | sed 's/.*authority:\s*//' | tr -d ' ')
+      case "$AUTHORITY" in
+        required)    SORT_KEY="1" ;;
+        recommended) SORT_KEY="2" ;;
+        *)           SORT_KEY="3" ;;
+      esac
+      APPLICABLE_FILES="${APPLICABLE_FILES}${SORT_KEY}|${mdfile}\n"
+    fi
+  done < <(find "$DEVDOCS_PATH" -name "*.md" -print0 2>/dev/null)
+
+  APPLICABLE_FILES=$(printf "$APPLICABLE_FILES" | sort | cut -d'|' -f2-)
+
+  while IFS= read -r mdfile; do
+    [ -z "$mdfile" ] && continue
+    TOTAL_LINES=$(wc -l < "$mdfile" 2>/dev/null || echo 0)
+    if [ "$TOTAL_LINES" -gt 200 ]; then
+      FILE_CONTENT=$(head -200 "$mdfile")
+      TRUNCATION_NOTE="_[Truncated at 200 lines — ${TOTAL_LINES} total.]_"
+    else
+      FILE_CONTENT=$(cat "$mdfile")
+      TRUNCATION_NOTE=""
+    fi
+
+    REL_PATH="${mdfile#${DEVDOCS_PATH}/}"
+    PROJECT_CONVENTIONS="${PROJECT_CONVENTIONS}
+
+#### \`${REL_PATH}\`
+${FILE_CONTENT}
+${TRUNCATION_NOTE}"
+  done <<< "$APPLICABLE_FILES"
+fi
+```
+
+### Step 3: Precedence rules to enforce
+
+When `CUSTOM_INSTRUCTIONS` or `PROJECT_CONVENTIONS` is non-empty, the architect MUST apply them throughout the plan. The precedence order is:
+
+```
+project/custom-instructions.md  ← HIGHEST PRIORITY (binding directives)
+    ↑
+other project/*.md              ← Authoritative project conventions
+agent/*.md                      ← ForgeDock/GitHub usage instructions
+agent memory                    ← Recalled knowledge
+agent defaults                  ← Built-in behaviors
+    ↓ LOWEST PRIORITY
+```
+
+`CUSTOM_INSTRUCTIONS` and `PROJECT_CONVENTIONS` are used in the `### Custom Instructions (HIGHEST PRECEDENCE)` and `### Project Conventions` sections of the FORGE:ARCHITECT output. If both are empty (devdocs path absent), these sections are replaced with skip notes.
+
+---
+
 ## Phase A1: Read Entry Points
 
 Identify every entry point that initiates the affected logic. Start from the files named in the investigation report.
@@ -226,6 +354,20 @@ Post the following as a GitHub comment on `{NUMBER}`:
 gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:ARCHITECT -->
 ## Implementation Plan for #{NUMBER}
 
+### Custom Instructions (HIGHEST PRECEDENCE)
+<!-- Binding directives from project/custom-instructions.md (Phase A0).
+     These override agent defaults, training knowledge, and all other context.
+     Builder MUST follow these exactly — violations are elevated to HIGH severity in review.
+     If devdocs path was absent or file not found: 'No custom-instructions.md found at
+     {DEVDOCS_PATH}/project/custom-instructions.md — skipping. Run `npx forgedock docs init`.' -->
+{CUSTOM_INSTRUCTIONS}
+
+### Project Conventions
+<!-- Authoritative project knowledge from project/*.md and agent/*.md files
+     with applies_to: work-on (Phase A0). Read these before finalizing the plan.
+     If devdocs path was absent or no applicable files found: 'No applicable devdocs found.' -->
+{PROJECT_CONVENTIONS}
+
 ### Affected Paths (ALL must be updated)
 | # | File | Function/Class | Change Required | Why |
 |---|------|----------------|-----------------|-----|
@@ -259,9 +401,10 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:ARCHITECT -->
 
 ## Timing Rules
 
-- Each file read: skip if the file exceeds 500 lines and only the first 100 lines are needed for structure
+- Phase A0 devdocs read: 30s total budget (path resolution + file enumeration + content reads); skip if exceeded
+- Each file read (A1): skip if the file exceeds 500 lines and only the first 100 lines are needed for structure
 - Each `grep -r` call: timeout after 10s, skip if exceeded
-- Total wall time budget: **3 minutes**. If budget exceeded, post partial results with `<!-- FORGE:ARCHITECT:PARTIAL -->` marker instead of `COMPLETE`.
+- Total wall time budget: **3 minutes** (A0 through A5 combined). If budget exceeded, post partial results with `<!-- FORGE:ARCHITECT:PARTIAL -->` marker instead of `COMPLETE`.
 
 ---
 
@@ -285,7 +428,16 @@ This module runs at **Step 3C.6** — after Context Gathering, before Implement:
 3C    → Builder Contract posted
 3C.5  → Context Gathering (FORGE:CONTEXT comment)
 3C.6  → [THIS MODULE] Architecture Planning (FORGE:ARCHITECT comment)
+          Phase A0: Read Custom Instructions and Project Conventions (highest precedence)
+          Phase A1: Read Entry Points
+          Phase A2: Trace the Data Flow
+          Phase A2.5: Pipeline Phase-Dependency Check
+          Phase A3: Consistency Rules
+          Phase A4: Sequence the Implementation
+          Phase A5: Risk Assessment
 3F    → Implement (builder reads plan, implements ALL affected paths)
 ```
 
 The builder agent reads the `<!-- FORGE:ARCHITECT -->` comment as its **primary input** before writing any code. The raw issue body is secondary context. If the architect step was skipped, the builder falls back to investigation report + contract.
+
+**Devdocs precedence** (Phase A0): `project/custom-instructions.md` has ABSOLUTE priority over all other context. The architect's plan must reflect any directives in that file — if custom instructions mandate a specific pattern, the implementation order and approach MUST follow it, even if the architect's general reasoning suggests an alternative. <!-- Added: forge#259 -->

package/commands/work-on/build/context.md

@@ -33,6 +33,117 @@ Parse from `$ARGUMENTS`:
 
 ---
 
+## Phase C-1: Authoritative Devdocs
+
+Read project-resident authoritative docs **before** any institutional-memory queries. Devdocs contain binding project knowledge (conventions, architecture, custom instructions) that must inform the builder's mental model from the start.
+
+**Time budget**: 30 seconds. If exceeded, log a skip note and continue to Phase C0.
+
+**Skip if**: `{REPO_PATH}` is not set, devdocs path does not exist, or path contains no markdown files.
+
+### Step 0: Resolve devdocs path
+
+Read `forge.yaml → devdocs.path` from the project root. Default to `devdocs` if the key is absent or unreadable.
+
+```bash
+DEVDOCS_PATH=""
+
+# Read forge.yaml directly from repo root (REPO_PATH points to the project root — no directory walk)
+FORGE_YAML_PATH="{REPO_PATH}/forge.yaml"
+
+if [ -f "$FORGE_YAML_PATH" ]; then
+  # Extract devdocs.path key (simple grep — value is on the same or next line under "devdocs:")
+  DEVDOCS_REL=$(grep -A5 '^devdocs:' "$FORGE_YAML_PATH" \
+    | grep '^\s*path:' \
+    | head -1 \
+    | sed 's/.*path:\s*//' \
+    | tr -d '"'"'"' \
+    | tr -d '[:space:]')
+fi
+
+# Default to "devdocs" if not found
+DEVDOCS_REL="${DEVDOCS_REL:-devdocs}"
+DEVDOCS_PATH="{REPO_PATH}/${DEVDOCS_REL}"
+
+if [ ! -d "$DEVDOCS_PATH" ]; then
+  echo "Devdocs path '${DEVDOCS_PATH}' does not exist — skipping Phase C-1 (no blocking)"
+  DEVDOCS_PATH=""
+fi
+```
+
+> **Note**: `devdocs/` must be tracked in git for the worktree to contain it. If the project gitignores `devdocs/`, the path will not exist in the worktree and this phase silently skips — this is by design. Run `git check-ignore -v devdocs/` to confirm tracking status.
+
+### Step 1: Enumerate and filter applicable files
+
+Find all `.md` files under `DEVDOCS_PATH`, parse YAML frontmatter, keep those with `work-on` in `applies_to`. Sort by authority (`required` first, then `recommended`, then `reference`).
+
+```bash
+DEVDOCS_APPLICABLE=""  # list of paths that apply
+
+if [ -n "$DEVDOCS_PATH" ]; then
+  # Find all markdown files recursively
+  while IFS= read -r -d '' mdfile; do
+    # Extract frontmatter block (between first two --- markers)
+    FRONTMATTER=$(awk '/^---/{c++; if(c==1){next} if(c==2){exit}} c==1{print}' "$mdfile" 2>/dev/null)
+
+    # Check if applies_to contains work-on
+    if echo "$FRONTMATTER" | grep -q 'applies_to:.*work-on'; then
+      AUTHORITY=$(echo "$FRONTMATTER" | grep 'authority:' | head -1 | sed 's/.*authority:\s*//' | tr -d ' ')
+      # Prepend sort key: 1=required, 2=recommended, 3=reference, 4=other
+      case "$AUTHORITY" in
+        required)    SORT_KEY="1" ;;
+        recommended) SORT_KEY="2" ;;
+        reference)   SORT_KEY="3" ;;
+        *)           SORT_KEY="4" ;;
+      esac
+      DEVDOCS_APPLICABLE="${DEVDOCS_APPLICABLE}${SORT_KEY}|${mdfile}\n"
+    fi
+  done < <(find "$DEVDOCS_PATH" -name "*.md" -print0 2>/dev/null)
+
+  # Sort by authority key and extract paths
+  DEVDOCS_APPLICABLE=$(printf "$DEVDOCS_APPLICABLE" | sort | cut -d'|' -f2-)
+fi
+
+if [ -z "$DEVDOCS_APPLICABLE" ]; then
+  echo "No devdocs files with 'applies_to: work-on' found — skipping Phase C-1 content read"
+fi
+```
+
+### Step 2: Read content of applicable files
+
+For each applicable file: read its content (max 200 lines; truncate with note if longer). Accumulate for output.
+
+```bash
+DEVDOCS_CONTENT=""
+
+while IFS= read -r mdfile; do
+  [ -z "$mdfile" ] && continue
+  TOTAL_LINES=$(wc -l < "$mdfile" 2>/dev/null || echo 0)
+  if [ "$TOTAL_LINES" -gt 200 ]; then
+    FILE_CONTENT=$(head -200 "$mdfile")
+    TRUNCATION_NOTE="_[Truncated at 200 lines — ${TOTAL_LINES} total. Read full file for complete context.]_"
+  else
+    FILE_CONTENT=$(cat "$mdfile")
+    TRUNCATION_NOTE=""
+  fi
+
+  # Relative path for display
+  REL_PATH="${mdfile#${DEVDOCS_PATH}/}"
+
+  DEVDOCS_CONTENT="${DEVDOCS_CONTENT}
+
+#### \`${REL_PATH}\`
+${FILE_CONTENT}
+${TRUNCATION_NOTE}"
+done <<< "$DEVDOCS_APPLICABLE"
+```
+
+### Step 3: Store for output
+
+`DEVDOCS_CONTENT` is used in the `### Authoritative Devdocs` section of the FORGE:CONTEXT comment output. If empty (path absent or no applicable files), the section is replaced with a skip note.
+
+---
+
 ## Phase C0: Prior Investigation Findings (from Gists)
 
 Scan the issue body for `<!-- FORGE:PRIOR_GIST: {url} -->` annotations embedded by the decompose or orchestrate phases (GIST-02). Also check for `<!-- FORGE:MILESTONE_INDEX: {url} -->` annotations — these reference a milestone-level index Gist (GIST-04) that aggregates all investigation Gist URLs for a milestone into a single reference. Both annotation types reference Knowledge Gists created during upstream investigation (GIST-01) and contain structured findings — verdict, root cause, recommendation, affected files — that the builder needs before writing code.
@@ -278,6 +389,14 @@ Post the following as a GitHub comment on `{NUMBER}`:
 gh issue comment {NUMBER} -R {GH_REPO} --body "<!-- FORGE:CONTEXT -->
 ## Implementation Context for #{NUMBER}
 
+### Authoritative Devdocs
+<!-- Project-resident authoritative knowledge read from devdocs/ (Phase C-1).
+     These files have the highest precedence — they override agent defaults and memory.
+     custom-instructions.md directives are BINDING and MUST be followed exactly.
+     If devdocs path was absent or no files matched applies_to: work-on — write:
+     'No devdocs found at {DEVDOCS_PATH} — skipping. Run `npx forgedock docs init` to scaffold.' -->
+{DEVDOCS_CONTENT}
+
 ### Prior Investigation Findings
 <!-- Summarized Knowledge Gist content from upstream investigations (Phase C0).
      If no FORGE:PRIOR_GIST annotations were found in the issue body: omit this section entirely.
@@ -317,11 +436,12 @@ gh issue comment {NUMBER} -R {GH_REPO} --body "<!-- FORGE:CONTEXT -->
 
 ## Timing Rules
 
+- Phase C-1 devdocs read: 30s total budget (file enumeration + content reads combined); skip if exceeded
 - Phase C0 `gh gist view` calls: timeout after 15s each, 30s total budget for all Gist fetches
 - Each `gh issue list` call: timeout after 20s, skip if exceeded
 - Each `gh pr list` call: timeout after 20s, skip if exceeded
 - Each `grep -r` call: timeout after 10s, skip if exceeded
-- Total wall time budget: **2 minutes** (C0 through C4 combined). If budget exceeded, post partial results with `<!-- FORGE:CONTEXT:PARTIAL -->` marker instead of `COMPLETE`.
+- Total wall time budget: **2 minutes** (C-1 through C4 combined). If budget exceeded, post partial results with `<!-- FORGE:CONTEXT:PARTIAL -->` marker instead of `COMPLETE`.
 
 ---
 
@@ -339,11 +459,19 @@ Skip this entire step (post nothing, return empty briefing) if:
 This module runs at **Step 3C.5** — after Builder Contract is posted, before Implement:
 
 ```
-3C  → Builder Contract posted
+3C   → Builder Contract posted
 3C.5 → [THIS MODULE] Context gathering (max 2 min)
-3F  → Implement (builder now has context briefing)
+         Phase C-1: Authoritative Devdocs (project-resident knowledge — highest precedence)
+         Phase C0:  Prior Investigation Findings (from Gists)
+         Phase C1:  Past Review Findings on These Files
+         Phase C2:  Past Bugs in the Same Module
+         Phase C3:  Related Code Paths
+         Phase C4:  Successful Similar Implementations
+3F   → Implement (builder now has context briefing)
 ```
 
 The builder agent reads the `<!-- FORGE:CONTEXT -->` comment before writing any code. If the context step was skipped, the builder proceeds with investigation report + contract only.
 
+**Devdocs precedence** (Phase C-1): Content from `project/custom-instructions.md` has the HIGHEST precedence of all context sources. Directives there override agent defaults, training knowledge, and all other devdocs. Other `project/*.md` and `agent/*.md` files with `applies_to: work-on` provide authoritative project conventions and ForgeDock usage guidance. <!-- Added: forge#259 -->
+
 When prior investigation Gists are available (Phase C0), the `### Prior Investigation Findings` section gives the builder cross-issue context — root causes, recommendations, and affected files from upstream investigations — without requiring manual Gist lookups. When a milestone-level index Gist exists (GIST-04), Phase C0 can resolve the index to discover all investigation Gists for the milestone from a single URL — providing full milestone-wide context automatically. <!-- Updated: forge#341 -->

package/commands/work-on.md

@@ -1100,4 +1100,4 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:TRAJECTORY -->
 - PR creation fails: check if branch pushed, if PR already exists
 - Merge conflicts: report to user, do NOT auto-resolve
 - gh CLI fails: check `gh auth status`
-- Label missing: `gh label create "{name}" --color {hex} -R {GH_REPO}`
+- Label missing: run `npx forgedock labels setup` (from the project directory, or pass `--repo owner/repo`) to idempotently bootstrap all ForgeDock-managed labels with canonical colors and descriptions. Alternatively: `gh label create "{name}" --color {hex} --description "Managed by ForgeDock." --force -R {GH_REPO}`

package/docs/CONFIG.md

@@ -23,6 +23,7 @@ echo "forge.yaml" >> .gitignore  # if your credentials path is sensitive
 | [`project_board`](#project_board-optional) | No | GitHub Projects v2 integration |
 | [`services`](#services-optional) | No | External service URLs and IDs |
 | [`review`](#review-optional) | No | Context injected into review agents |
+| [`devdocs`](#devdocs-optional) | No | Devdocs knowledge tree path |
 | [`verification`](#verification-optional) | No | Health-check patterns |
 | [`billing`](#billing-optional) | No | Enable financial integrity audit phase |
 
@@ -305,6 +306,39 @@ review:
 
 ---
 
+## `devdocs` (OPTIONAL)
+
+Path configuration for the devdocs knowledge tree. Pipeline agents (work-on, review-pr, etc.) read these files as **authoritative project knowledge** before acting.
+
+Run `npx forgedock docs init` to scaffold the tree from ForgeDock's seed templates into the configured path.
+
+```yaml
+devdocs:
+  path: "devdocs"
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `path` | string (relative path) | No | Path to the devdocs tree, relative to project root. Default: `devdocs`. |
+
+**Commands that use this section**: `docs init`, `work-on/build/context` (Phase C-1), `work-on/build/architect` (Phase A0)
+
+### Migration from `review.context`
+
+If you previously stored project context in `forge.yaml → review.context`, move that content into the appropriate devdocs file after running `npx forgedock docs init`:
+
+| `review.context` content | Target devdocs file |
+|--------------------------|---------------------|
+| Architecture decisions | `devdocs/project/architecture.md` |
+| Tech stack details | `devdocs/project/stack.md` |
+| Coding conventions | `devdocs/project/conventions.md` |
+| Project terminology | `devdocs/project/glossary.md` |
+| ForgeDock usage notes | `devdocs/agent/using-forgedock.md` |
+
+Agents read devdocs files as binding source-of-truth, so they receive richer context than the single `review.context` string.
+
+---
+
 ## `verification` (OPTIONAL)
 
 Service health-check patterns for the quality gate and validate commands.
@@ -382,6 +416,47 @@ billing:
 
 ---
 
+## Label Bootstrap
+
+ForgeDock manages a canonical set of GitHub labels for use across all pipeline commands. Labels cover workflow state, priority, review findings, audit findings, and category classification.
+
+### Bootstrap command
+
+```bash
+# Create/update all ForgeDock-managed labels on the repo defined in forge.yaml:
+npx forgedock labels setup
+
+# Or target a specific repo explicitly:
+npx forgedock labels setup --repo owner/repo
+```
+
+Running this command is idempotent — it creates labels that don't exist and updates the color/description of labels that do. Safe to re-run at any time.
+
+**When to run it**: Once after `npx forgedock install`, or whenever a pipeline command fails with "label not found". The command bootstraps every label the pipeline relies on.
+
+### Canonical label set
+
+The full manifest lives in [`bin/labels.json`](../bin/labels.json) in the ForgeDock package. Each label has a fixed hex color and a description attributing it to ForgeDock.
+
+| Family | Labels |
+|--------|--------|
+| Priority | `priority:P0` `priority:P1` `priority:P2` `priority:P3` |
+| Workflow | `workflow:investigating` `workflow:ready-to-build` `workflow:building` `workflow:in-review` `workflow:merged` `workflow:decomposed` `workflow:invalid` |
+| Pipeline | `needs-human` `review-finding` `needs-validation` `validated` `false-positive` `staging-review` `audit-finding` `orchestration-metrics` `health-report` |
+| Category | `bug` `enhancement` `feature` `refactor` `dead-code` `improvement` `documentation` `qa` `security` `performance` |
+
+### Colors
+
+Colors are grouped by semantic meaning:
+- **Critical/error** (`#B60205`): `priority:P0`, `security`
+- **High/warning-red** (`#D93F0B`): `priority:P1`, `review-finding`, `audit-finding`
+- **Medium/yellow** (`#FBCA04`): `priority:P2`, `needs-validation`
+- **Low/green** (`#C2E0C6`, `#0E8A16`): `priority:P3`, `workflow:merged`, `validated`
+- **Blue pipeline** (`#1D76DB`, `#0075CA`, `#0052CC`): active workflow states
+- **Neutral** (`#CCCCCC`, `#E4E669`): terminal/dismissal states
+
+---
+
 ## Config Reading Conventions
 
 ForgeDock commands use two accepted patterns for reading `forge.yaml`:
@@ -393,6 +468,48 @@ Do **not** mix the two patterns for the same block of variables (e.g., `yq` with
 
 ---
 
+## CLAUDE.md Integration
+
+ForgeDock can inject a managed usage block into your project's `CLAUDE.md` so every Claude Code session opened in the repo automatically knows that ForgeDock drives development here and which commands to use.
+
+### How It Works
+
+Running `npx forgedock init` or `npx forgedock integrate` writes a marker-bounded block into `CLAUDE.md`:
+
+```
+<!-- BEGIN FORGEDOCK -->
+## ForgeDock — Autonomous Development Pipeline
+...command index and conventions...
+<!-- END FORGEDOCK -->
+```
+
+The block is **idempotent** — re-running replaces only the managed section and leaves all other `CLAUDE.md` content untouched. If `CLAUDE.md` does not exist, it is created.
+
+If `AGENTS.md` already exists in the project root, the same block is mirrored into it.
+
+### Commands
+
+| Command | Action |
+|---------|--------|
+| `npx forgedock init` | Generates `forge.yaml` **and** injects the CLAUDE.md block |
+| `npx forgedock integrate` | Injects/refreshes the block without modifying `forge.yaml` |
+
+### Opting Out
+
+To prevent ForgeDock from managing the block, remove the `<!-- BEGIN FORGEDOCK -->` / `<!-- END FORGEDOCK -->` markers from `CLAUDE.md`. Without the markers, subsequent runs will append a new block rather than replacing one — so if you want to opt out permanently, delete or omit the markers **and** do not run `integrate` again.
+
+Alternatively, keep the markers but edit the content between them freely — ForgeDock will replace that section on the next run, so any manual edits inside the markers will be overwritten.
+
+### Re-generating
+
+The command index inside the block is auto-generated from the `description:` frontmatter in each `commands/*.md` file. To refresh it after a ForgeDock update:
+
+```bash
+npx forgedock integrate
+```
+
+---
+
 ## Complete Example
 
 See [`forge.yaml.example`](../forge.yaml.example) at the repository root for a fully annotated example covering all sections.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "GitHub as a knowledge graph for AI agents. Autonomous dev pipeline for Claude Code.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"
@@ -36,6 +36,7 @@
     "commands/",
     "docs/",
     "scripts/",
+    "templates/",
     "LICENSE",
     "README.md"
   ],

package/templates/devdocs/README.md

@@ -0,0 +1,96 @@
+---
+authority: required
+scope: project
+applies_to: [work-on, review-pr, issue, orchestrate, quality-gate]
+---
+
+# DevDocs — Authoritative Knowledge Base
+
+This directory contains the authoritative knowledge base for your project. Pipeline agents (ForgeDock commands) read these files as **binding source-of-truth** before acting — not as suggestions.
+
+---
+
+## Purpose
+
+DevDocs bridge the gap between what agents know by default and what your project requires. They answer:
+
+- How do we use ForgeDock in this project? (`agent/using-forgedock.md`)
+- How do we use GitHub in this project? (`agent/using-github.md`)
+- What templates do we use? (`templates/`)
+- What is this project's tech stack, architecture, and conventions? (`project/`)
+
+---
+
+## Directory Structure
+
+```
+devdocs/
+  README.md                     ← you are here
+  agent/
+    using-forgedock.md          ← ForgeDock pipeline how-to (all phases, lanes, commands)
+    using-github.md             ← GitHub CLI, branch naming, labels, commit discipline
+  templates/
+    issue.md                    ← reusable issue body template
+    pull-request.md             ← reusable PR body template
+    commit-convention.md        ← conventional commit reference
+    review-finding.md           ← review-finding issue template
+  project/
+    custom-instructions.md      ← user binding directives (HIGHEST precedence)
+    stack.md                    ← tech stack description
+    architecture.md             ← system and domain overview
+    conventions.md              ← coding standards and patterns
+    glossary.md                 ← domain terms and definitions
+```
+
+---
+
+## Precedence Rules
+
+When a conflict arises between different knowledge sources, agents follow this priority order:
+
+| Priority | Source | Description |
+|----------|--------|-------------|
+| 1 (highest) | `project/custom-instructions.md` | Explicit user-authored directives. Always wins. |
+| 2 | Other `project/*.md` files | Authoritative project context (stack, architecture, conventions) |
+| 3 | `agent/*.md` files | Authoritative ForgeDock/GitHub usage instructions |
+| 4 | `templates/*.md` files | Standard templates (lower authority than instructions) |
+| 5 | Agent memory | Recalled knowledge from past sessions |
+| 6 (lowest) | Agent defaults | Built-in behaviors when no other source applies |
+
+**Rule**: When `custom-instructions.md` says X, agents do X — even if their training or memory says otherwise.
+
+---
+
+## Authority Levels
+
+Each file declares an `authority` field in its frontmatter:
+
+| Authority | Meaning |
+|-----------|---------|
+| `required` | Agent MUST read this file before acting in its domain |
+| `recommended` | Agent SHOULD read this file; improves output quality |
+| `reference` | Agent MAY consult this file; informational only |
+
+---
+
+## How Agents Use DevDocs
+
+1. **Before investigating**: Read `agent/using-forgedock.md` and `project/custom-instructions.md`
+2. **Before building**: Read `agent/using-github.md`, relevant `project/*.md`, applicable `templates/*.md`
+3. **Before reviewing**: Read `project/conventions.md`, `project/stack.md`
+4. **Always**: Treat `project/custom-instructions.md` as the final authority
+
+---
+
+## Regeneration
+
+If this directory was scaffolded by `npx forgedock docs init`, re-running that command will add any new template files introduced in newer ForgeDock versions. It will **not** overwrite files you have edited (idempotent).
+
+---
+
+## Maintenance Notes
+
+- Edit `project/*.md` files to reflect your project's actual stack, architecture, and conventions
+- Edit `project/custom-instructions.md` to add binding directives for your project
+- Do NOT edit `agent/*.md` unless you want to override ForgeDock's default behavior for this project
+- `templates/*.md` files can be customized; changes affect what pipeline agents use as templates