feed-the-machine 1.0.0

package/ftm-git/references/patterns/SECRET-PATTERNS.md

@@ -0,0 +1,104 @@
+# Secret Patterns — Extended Pattern Library
+
+Full regex pattern library for Phase 1 scanning. Tier 1 patterns are high-confidence; Tier 2 require surrounding context validation.
+
+---
+
+## Tier 1: High-Confidence Patterns (almost certainly real secrets)
+
+These patterns have distinctive prefixes or structures that make false positives rare. Run in parallel.
+
+```
+# AWS
+AKIA[0-9A-Z]{16}                                          # AWS Access Key ID
+amzn\.mws\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}  # AWS MWS
+
+# GitHub
+ghp_[A-Za-z0-9_]{36}                                      # GitHub PAT (classic)
+gho_[A-Za-z0-9_]{36}                                      # GitHub OAuth
+ghu_[A-Za-z0-9_]{36}                                      # GitHub user token
+ghs_[A-Za-z0-9_]{36}                                      # GitHub server token
+github_pat_[A-Za-z0-9_]{82}                                # GitHub fine-grained PAT
+
+# Slack
+xoxb-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24}           # Slack bot token
+xoxp-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24,34}        # Slack user token
+xoxa-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24,34}        # Slack app token
+xoxr-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24,34}        # Slack refresh token
+
+# Google
+AIza[0-9A-Za-z\-_]{35}                                    # Google API key
+
+# Stripe
+sk_live_[0-9a-zA-Z]{24,}                                  # Stripe secret key (live)
+sk_test_[0-9a-zA-Z]{24,}                                  # Stripe secret key (test)
+rk_live_[0-9a-zA-Z]{24,}                                  # Stripe restricted key
+
+# Other services
+SG\.[A-Za-z0-9\-_]{22}\.[A-Za-z0-9\-_]{43}               # SendGrid
+SK[0-9a-fA-F]{32}                                          # Twilio
+npm_[A-Za-z0-9]{36}                                        # npm token
+pypi-[A-Za-z0-9\-_]{100,}                                 # PyPI token
+glpat-[A-Za-z0-9\-_]{20,}                                 # GitLab PAT
+-----BEGIN (RSA|DSA|EC|OPENSSH|PGP) PRIVATE KEY-----      # Private keys
+```
+
+---
+
+## Tier 2: Context-Dependent Patterns (need surrounding context to confirm)
+
+These match common assignment patterns. Check that the value isn't a placeholder, empty string, or env var reference before flagging:
+
+```
+# Generic key/secret assignments — flag if value looks real (not placeholder)
+(api_key|apikey|api-key)\s*[:=]\s*["']?[A-Za-z0-9\-_]{16,}["']?
+(secret|secret_key|client_secret)\s*[:=]\s*["']?[A-Za-z0-9\-_]{16,}["']?
+(password|passwd|pwd)\s*[:=]\s*["']?[^\s"']{8,}["']?
+(token|access_token|auth_token)\s*[:=]\s*["']?[A-Za-z0-9\-_.]{16,}["']?
+(database_url|db_url|connection_string)\s*[:=]\s*["']?[^\s"']{20,}["']?
+
+# Bearer tokens in code
+bearer\s+[A-Za-z0-9\-._~+/]{20,}
+
+# Webhook URLs with tokens
+https://hooks\.slack\.com/services/T[A-Z0-9]{8,}/B[A-Z0-9]{8,}/[a-zA-Z0-9]{24}
+```
+
+---
+
+## What to Ignore (false positive suppression)
+
+Skip matches that are clearly not real secrets:
+
+- Values that are `""`, `''`, `None`, `null`, `undefined`, `TODO`, `CHANGEME`, `your-key-here`, `xxx`, `placeholder`, `example`, `test`, `dummy`, `fake`, `sample`
+- References to environment variables: `os.environ[`, `process.env.`, `ENV[`, `${`, `os.getenv(`
+- Lines that are comments (`#`, `//`, `/*`, `--`)
+- Files in `node_modules/`, `.git/`, `vendor/`, `__pycache__/`, `dist/`, `build/`
+- Files that are themselves `.env.example`, `.env.sample`, `.env.template`
+- Lock files (`package-lock.json`, `yarn.lock`, `Gemfile.lock`, `poetry.lock`)
+- Test fixtures where the "secret" is obviously fake (e.g., `test_api_key = "sk_test_abc123"` in a test file — but still flag `sk_live_*` in test files, those are real)
+
+---
+
+## Severity Classification
+
+After validation, findings are sorted by severity:
+
+| Severity | Meaning |
+|---|---|
+| **CRITICAL** | Tier 1 match (high-confidence secret) in a tracked or staged file |
+| **HIGH** | Tier 2 confirmed match in a tracked or staged file |
+| **MEDIUM** | `.env` file not in `.gitignore`, or secret in a fallback default |
+| **LOW** | Secret in a gitignored file but the gitignore rule might be fragile |
+
+---
+
+## Per-Finding Record Format
+
+For each finding, record:
+- **file**: absolute path
+- **line**: line number
+- **pattern**: which pattern matched
+- **tier**: 1 or 2
+- **value_preview**: first 8 chars + `...` + last 4 chars (never log the full secret)
+- **context**: the surrounding code (with the secret value masked)

package/ftm-git/references/protocols/REMEDIATION.md

@@ -0,0 +1,139 @@
+# Remediation Protocol — Auto-Fix Steps
+
+Detailed remediation steps for secrets found during Phase 1–2 scanning. Apply in sequence for each finding.
+
+---
+
+## Phase 3: Auto-Remediate
+
+For each finding, apply the appropriate fix automatically. The goal is to make the code safe without breaking functionality.
+
+### Step 1: Ensure .env infrastructure exists
+
+Check for a `.env` file in the project root. If it doesn't exist, create one with a header comment:
+
+```
+# Environment variables — DO NOT COMMIT THIS FILE
+# Copy .env.example for the template, fill in real values locally
+```
+
+Check `.gitignore` for `.env` coverage. If missing, add:
+```
+# Environment files with secrets
+.env
+.env.local
+.env.production
+.env.staging
+.env.*.local
+```
+
+### Step 2: Extract secrets to .env
+
+For each finding:
+
+1. **Choose an env var name** — derive it from the context. If the code says `STRIPE_API_KEY = "sk_live_..."`, the env var is `STRIPE_API_KEY`. If it says `api_key: "AIza..."`, infer from the file/service context (e.g., `GOOGLE_API_KEY`). Use SCREAMING_SNAKE_CASE.
+
+2. **Add to .env** — append `VAR_NAME=<actual-secret-value>` to `.env`. If the var already exists, don't duplicate it.
+
+3. **Add to .env.example** — create or update `.env.example` with `VAR_NAME=your-value-here` so other developers know the variable exists without seeing the real value.
+
+### Step 3: Refactor source files
+
+Replace the hardcoded secret with an env var reference. Match the language/framework:
+
+| Language | Pattern |
+|---|---|
+| Python | `os.environ["VAR_NAME"]` or `os.getenv("VAR_NAME")` (match existing style in file) |
+| JavaScript/TypeScript | `process.env.VAR_NAME` |
+| Ruby | `ENV["VAR_NAME"]` or `ENV.fetch("VAR_NAME")` |
+| Go | `os.Getenv("VAR_NAME")` |
+| Java | `System.getenv("VAR_NAME")` |
+| Shell/Bash | `$VAR_NAME` or `${VAR_NAME}` |
+| YAML/JSON config | `${VAR_NAME}` (if the framework supports interpolation) or add a comment pointing to the env var |
+
+If the file doesn't already import the env-reading module (e.g., `import os` in Python, `require('dotenv').config()` in Node), add the import. Check if the project uses `python-dotenv`, `dotenv` (Node), or similar — if so, use the project's existing pattern for loading env vars.
+
+### Step 4: Unstage remediated files
+
+After refactoring, make sure the `.env` file (with real secrets) is NOT staged:
+
+```bash
+git reset HEAD .env 2>/dev/null  # unstage if accidentally staged
+```
+
+Stage the refactored source files (which now reference env vars instead of hardcoded secrets):
+
+```bash
+git add <refactored-files>
+```
+
+### Step 5: Verify the fix
+
+Re-run Phase 1 scan on the refactored files to confirm the secrets are gone. If any remain, loop back and fix. Do not proceed until the scan is clean.
+
+---
+
+## Phase 4: Report
+
+After remediation (or if the scan was clean from the start), produce a summary:
+
+**Clean scan:**
+```
+ftm-git: Clean scan. 0 secrets found in <N> files scanned. Safe to commit.
+```
+
+**After remediation:**
+```
+ftm-git: Found <N> hardcoded secrets. Auto-remediated:
+
+  CRITICAL: sk_live_**** in src/payments.py:42 -> STRIPE_SECRET_KEY
+  HIGH:     AIza**** in config/google.ts:18 -> GOOGLE_API_KEY
+  MEDIUM:   .env was not in .gitignore -> added
+
+Actions taken:
+  - Extracted <N> secrets to .env (gitignored)
+  - Created/updated .env.example with placeholder vars
+  - Refactored <N> source files to use env var references
+  - Updated .gitignore
+
+Verify the app still works with the new env var setup, then commit.
+```
+
+**Blocked (auto-fix not possible):**
+
+Some secrets can't be auto-fixed — for example, a private key embedded in a binary file, or a secret in a format the skill can't safely refactor. In these cases:
+
+```
+ftm-git: BLOCKED. Found secrets that require manual remediation:
+
+  CRITICAL: Private key in assets/cert.pem:1
+            -> Move this file outside the repo and reference via path env var
+
+  Action required: Fix the above manually, then run ftm-git again.
+```
+
+---
+
+## Phase 5: Git History Check (Manual Invocation Only)
+
+When explicitly asked to do a deep scan (e.g., "scan the repo history for secrets"), also check past commits. This is expensive so it only runs on explicit request, not as part of the pre-commit gate.
+
+```bash
+git log --all --diff-filter=A --name-only --pretty=format:"%H" -- "*.env" "*.pem" "*.key" "*credentials*" "*secret*"
+```
+
+For each historically added sensitive file, check if it's still in the current tree. If it was added and later removed, warn that the secret is still in git history and suggest:
+
+1. Rotate the credential immediately (it's compromised)
+2. Use `git filter-repo` or BFG Repo Cleaner to purge from history if needed
+
+---
+
+## Operating Principles
+
+1. **Block first, fix second.** Never let a secret through while figuring out the fix. The commit waits.
+2. **Zero false negatives over zero false positives.** It's better to flag something that turns out to be harmless than to miss a real key.
+3. **Never log full secrets.** In all output, mask secret values. Show only enough to identify which secret it is (first 8 + last 4 chars).
+4. **Env vars are the escape hatch.** The remediation pattern is always: secret goes to gitignored .env, code references the env var.
+5. **Existing patterns win.** If the project already uses dotenv, Vault, AWS Secrets Manager, or any other secret management system, match that pattern rather than introducing a new one.
+6. **Test files are not exempt.** A real `sk_live_*` key in a test file is just as dangerous as one in production code. Only `sk_test_*` with obviously fake values get a pass.

package/ftm-git/scripts/pre-commit-secrets.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# ftm-git pre-commit hook — blocks commits containing hardcoded secrets
+# Installed by the ftm-git skill on first invocation. Safe to remove with:
+#   rm .git/hooks/pre-commit  (or edit to remove the ftm-git section)
+#
+# This hook scans staged files only (fast). The full ftm-git skill does
+# deeper scanning with context validation and auto-remediation — this is
+# the safety net that catches what slips through.
+
+set -euo pipefail
+
+RED='\033[0;31m'
+YELLOW='\033[0;33m'
+NC='\033[0m'
+
+# Get list of staged files (excluding deletions)
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACMR 2>/dev/null || true)
+if [ -z "$STAGED_FILES" ]; then
+  exit 0
+fi
+
+# Skip binary files, lock files, and vendored directories
+FILTERED_FILES=""
+for f in $STAGED_FILES; do
+  case "$f" in
+    node_modules/*|vendor/*|.git/*|__pycache__/*|dist/*|build/*) continue ;;
+    package-lock.json|yarn.lock|Gemfile.lock|poetry.lock|pnpm-lock.yaml) continue ;;
+    *.png|*.jpg|*.gif|*.ico|*.woff|*.woff2|*.ttf|*.eot|*.pdf|*.zip|*.tar*) continue ;;
+    .env.example|.env.sample|.env.template) continue ;;
+    *) FILTERED_FILES="$FILTERED_FILES $f" ;;
+  esac
+done
+
+if [ -z "$FILTERED_FILES" ]; then
+  exit 0
+fi
+
+FOUND=0
+FINDINGS=""
+
+# Tier 1: High-confidence patterns — these almost never false-positive
+# We scan staged content (not working tree) to catch exactly what would be committed
+PATTERNS=(
+  'AKIA[0-9A-Z]{16}'                                            # AWS Access Key ID
+  'ghp_[A-Za-z0-9_]{36}'                                        # GitHub PAT
+  'gho_[A-Za-z0-9_]{36}'                                        # GitHub OAuth
+  'ghu_[A-Za-z0-9_]{36}'                                        # GitHub user token
+  'ghs_[A-Za-z0-9_]{36}'                                        # GitHub server token
+  'github_pat_[A-Za-z0-9_]{82}'                                  # GitHub fine-grained PAT
+  'xoxb-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24}'              # Slack bot token
+  'xoxp-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24,34}'          # Slack user token
+  'xoxa-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24,34}'          # Slack app token
+  'AIza[0-9A-Za-z\-_]{35}'                                      # Google API key
+  'sk_live_[0-9a-zA-Z]{24,}'                                    # Stripe live secret
+  'sk_test_[0-9a-zA-Z]{24,}'                                    # Stripe test secret
+  'rk_live_[0-9a-zA-Z]{24,}'                                    # Stripe restricted
+  'SG\.[A-Za-z0-9\-_]{22}\.[A-Za-z0-9\-_]{43}'                 # SendGrid
+  'SK[0-9a-fA-F]{32}'                                            # Twilio
+  'npm_[A-Za-z0-9]{36}'                                          # npm token
+  'glpat-[A-Za-z0-9\-_]{20,}'                                   # GitLab PAT
+  '-----BEGIN (RSA|DSA|EC|OPENSSH|PGP) PRIVATE KEY-----'        # Private keys
+)
+
+for f in $FILTERED_FILES; do
+  # Get the staged version of the file (what would actually be committed)
+  CONTENT=$(git show ":$f" 2>/dev/null || true)
+  if [ -z "$CONTENT" ]; then
+    continue
+  fi
+
+  for pattern in "${PATTERNS[@]}"; do
+    MATCHES=$(echo "$CONTENT" | grep -nE "$pattern" 2>/dev/null || true)
+    if [ -n "$MATCHES" ]; then
+      while IFS= read -r match; do
+        LINE_NUM=$(echo "$match" | cut -d: -f1)
+        # Mask the secret value in output (show first 8 chars only)
+        MASKED=$(echo "$match" | cut -d: -f2- | sed -E 's/([A-Za-z0-9_\-]{8})[A-Za-z0-9_\-]{8,}/\1****/g')
+        FINDINGS="${FINDINGS}\n  ${RED}BLOCKED${NC}  $f:$LINE_NUM  $MASKED"
+        FOUND=$((FOUND + 1))
+      done <<< "$MATCHES"
+    fi
+  done
+done
+
+# Also check: is a .env file being committed?
+for f in $STAGED_FILES; do
+  case "$f" in
+    .env|.env.local|.env.production|.env.staging|.env.*.local)
+      FINDINGS="${FINDINGS}\n  ${YELLOW}WARNING${NC}  $f is staged — this file typically contains secrets and should be gitignored"
+      FOUND=$((FOUND + 1))
+      ;;
+  esac
+done
+
+if [ "$FOUND" -gt 0 ]; then
+  echo ""
+  echo -e "${RED}ftm-git: COMMIT BLOCKED — $FOUND secret(s) detected in staged files${NC}"
+  echo ""
+  echo -e "$FINDINGS"
+  echo ""
+  echo "To fix: run /ftm-git for auto-remediation, or manually:"
+  echo "  1. Move secrets to .env (gitignored)"
+  echo "  2. Replace hardcoded values with env var references"
+  echo "  3. Stage the cleaned files and commit again"
+  echo ""
+  echo "To bypass (NOT recommended): git commit --no-verify"
+  exit 1
+fi
+
+exit 0

package/ftm-git.yml

@@ -0,0 +1,2 @@
+name: ftm-git
+description: Secret scanning and credential safety gate for git operations. Prevents API keys, tokens, passwords, and other secrets from ever being committed or pushed to remote repositories. Scans staged files, working tree, and git history for hardcoded credentials using regex pattern matching, then auto-remediates by extracting secrets to gitignored .env files and replacing hardcoded values with env var references. Use when user says "scan for secrets", "check for keys", "audit credentials", "ftm-git", "secret scan", "remove api keys", "check before push", or any time git commit/push operations are about to happen. Also auto-invoked by ftm-executor and ftm-mind before any commit or push operation. Even if the user just says "commit this" or "push to remote", this skill MUST run first. Do NOT use for general git workflow operations like branching or merging — that's git-workflow territory. This skill is specifically the security gate.

package/ftm-intent/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: ftm-intent
+description: Manages the hierarchical INTENT.md documentation layer — root index with architecture decisions and module map, plus per-module INTENT.md files with function-level entries (does/why/relationships/decisions). Use when creating or updating intent documentation, bootstrapping a new project's intent layer, or when user says "update intent", "document intent", "ftm-intent", "what does this function do". Auto-invoked by ftm-executor after every commit to keep intent documentation in sync with code changes.
+---
+
+## Events
+
+### Emits
+- `documentation_updated` — when one or more INTENT.md files are written or modified to reflect new or changed code
+- `task_completed` — when the full intent sync pass completes (bootstrap or incremental)
+
+### Listens To
+- `code_committed` — fast-path: automatically sync INTENT.md entries for every changed function after each commit
+
+# Intent Documentation Manager
+
+Manages the hierarchical INTENT.md documentation layer. This is the contract layer that Codex reads during code review and that enables conflict detection between Claude's intent and Codex's fixes. The "Why" field is what prevents Codex from reverting deliberate design choices.
+
+## Graph-Powered Mode (ftm-map integration)
+
+Before running the standard analysis, check if the project has a code knowledge graph:
+
+```bash
+if [ -f ".ftm-map/map.db" ]; then
+    # Use graph for faster, more consistent analysis
+    ftm-map/scripts/.venv/bin/python3 ftm-map/scripts/views.py generate-intent "$PROJECT_ROOT"
+else
+    # Fall back to standard file-by-file analysis below
+fi
+```
+
+When `.ftm-map/map.db` exists:
+1. Delegate to `views.py generate-intent` which reads the graph and produces INTENT.md files
+2. The graph path is faster (single DB query vs. reading every file) and more consistent (same analysis for every commit)
+3. Supports `--files` flag for incremental: `views.py generate-intent --files changed1.ts,changed2.py`
+
+When `.ftm-map/map.db` does NOT exist:
+- Fall back to the existing Bootstrap/Incremental modes below
+- The behavior is identical to the current skill — no breaking change
+
+This integration means ftm-intent automatically gets better when ftm-map is available, without requiring migration.
+
+## Two Modes of Operation
+
+### Bootstrap Mode (no INTENT.md exists)
+Scan the codebase from scratch and create the full hierarchy.
+
+1. Use Glob to discover all source files and identify module boundaries
+2. Use Read/Grep to understand key functions in each module
+3. Create root INTENT.md at the project root
+4. Create per-module INTENT.md files for each module directory
+5. Populate all entries based on what the code actually does
+
+### Incremental Mode (INTENT.md already exists)
+Read the current state and update only what changed.
+
+1. Read root INTENT.md and all relevant module INTENT.md files
+2. Identify what's missing: new functions without entries, new modules without INTENT.md
+3. Identify what's stale: entries for deleted or renamed functions
+4. Update only the affected entries and module map rows — do not regenerate from scratch
+
+## Root INTENT.md Template
+
+Create at the project root. This is the "subway map" — high level routing to module detail.
+
+```markdown
+# [Project Name] — Intent
+
+## Vision
+[2-3 sentence summary of what this project does and why it exists]
+
+## Architecture Decisions
+| Decision | Choice | Reasoning |
+|---|---|---|
+| [decision point] | [what was chosen] | [why this was chosen over alternatives] |
+
+## Module Map
+| Module | Purpose | Key Relationships |
+|---|---|---|
+| [path/to/module] | [what this module does in one sentence] | [depends on X / depended by Y] |
+
+## Cross-Cutting Decisions
+- [pattern name]: [what it is and why it applies everywhere]
+```
+
+**Rules for root INTENT.md:**
+- Vision: Written once, updated only if the project's purpose changes
+- Architecture Decisions: Add a row every time a non-obvious architectural choice is made
+- Module Map: Add a row when a new module directory is created; remove when deleted; must stay in sync with actual filesystem
+- Cross-Cutting Decisions: Patterns that apply across 3+ modules (error handling strategy, auth approach, data fetching pattern, etc.)
+
+## Per-Module INTENT.md Template
+
+Create inside each module directory (e.g., `src/auth/INTENT.md`). This is the "street map" — ground level function detail.
+
+```markdown
+# [Module Name] — Intent
+
+## Functions
+
+### functionName(param1: Type, param2: Type) → ReturnType
+- **Does**: [one sentence — what it does, not how]
+- **Why**: [why this function exists, what problem it solves, why this approach over alternatives]
+- **Relationships**: [calls X, called by Y, reads from Z store, mutates W]
+- **Decisions**: [deliberate choices that might look wrong to an outside reviewer — "uses polling instead of websockets because..."]
+
+### anotherFunction(param: Type) → ReturnType
+- **Does**: ...
+- **Why**: ...
+- **Relationships**: ...
+- **Decisions**: ...
+```
+
+**Rules for per-module INTENT.md:**
+- Every exported function MUST have an entry
+- Every entry MUST have all four fields (Does / Why / Relationships / Decisions)
+- If there are no deliberate decisions, write "None" in the Decisions field — do not omit the field
+- Include the full function signature with types — this helps with quick lookup and makes entries grep-able
+- Keep each field to one sentence. This is a contract, not prose documentation.
+
+## When to Update
+
+| Event | Action |
+|---|---|
+| New function created | Add entry to module's INTENT.md |
+| Function behavior changed | Update Does / Why / Decisions fields |
+| Function deleted | Remove entry from module's INTENT.md |
+| New module directory created | Create module INTENT.md + add row to root module map |
+| Module deleted | Remove module INTENT.md + remove row from root module map |
+| Architecture decision made | Add row to root INTENT.md decisions table |
+| Cross-cutting pattern established | Add entry to root Cross-Cutting Decisions section |
+
+## The Why Field — Most Important
+
+The "Why" field is what makes this system valuable. It is the explicit record of deliberate choices that might look like bugs or inefficiencies to a reviewer who wasn't there when the decision was made.
+
+Good Why entries:
+- "Exists because the provider SDK doesn't expose a batch endpoint — each call must be sequential"
+- "Uses pessimistic locking instead of optimistic because this resource has high write contention in production"
+- "Fetches on every render instead of caching because this data changes in real time and stale reads cause downstream errors"
+
+Bad Why entries:
+- "Needed for the feature to work"
+- "Required by the system"
+- "Called by the auth flow"
+
+If you can't write a clear Why, it means the original reasoning wasn't captured. Try to infer it from surrounding code, comments, or git history. If it's truly unknown, write "Why unknown — inferred from usage: [your inference]".
+
+## Format Contract
+
+Codex reads INTENT.md files during code review to detect conflicts between stated intent and proposed changes. For this to work, the format must be consistent.
+
+**Required format — do not deviate:**
+- Section header: `### functionName(params) → ReturnType`
+- Four bullet fields in order: `- **Does**:`, `- **Why**:`, `- **Relationships**:`, `- **Decisions**:`
+- No prose paragraphs inside function entries
+- No nested bullets inside a field — one sentence per field, always
+
+If a function is complex enough that one sentence isn't enough, the function is probably doing too much. Document what it does at the boundary level, not the implementation level.
+
+## Discovery Commands
+
+Use these to find what needs to be documented:
+
+- Find all module directories: `Glob("src/**/")` or `Glob("lib/**/")`
+- Find existing INTENT.md files: `Glob("**/INTENT.md")`
+- Find all exported functions in a module: `Grep("^export (function|const|async function)", path="src/module/")`
+- Find functions called by a specific function: read the function body and trace calls
+- Find what calls a specific function: `Grep("functionName", type="ts")` or equivalent
+
+## Bootstrap Execution Order
+
+When creating the intent layer from scratch:
+
+1. Read the project root README or package.json to understand the project vision
+2. Run `Glob("src/**/")` (or equivalent for the project structure) to discover modules
+3. For each module, read key files to understand what functions exist and what they do
+4. Draft root INTENT.md — vision, then module map (one row per module), then architecture decisions from what you observed, then cross-cutting patterns
+5. For each module, draft module INTENT.md — one entry per exported function
+6. Write all files
+7. Report: list of files created, count of functions documented, any functions where Why was unclear
+
+## Incremental Execution Order
+
+When updating after changes:
+
+1. Read root INTENT.md
+2. Read the INTENT.md for affected modules (or all modules if unsure what changed)
+3. Compare against current code — use Grep to find functions that don't have entries, entries that don't have corresponding functions
+4. Write updates — add missing entries, remove stale entries, update changed fields
+5. If new modules were added, create their INTENT.md and add rows to root module map
+6. Report: list of files updated, entries added, entries removed, entries modified
+
+---
+
+### Auto-Invocation by ftm-executor
+
+This skill's format is used by ftm-executor's documentation pipeline. After every commit during plan execution, agents update INTENT.md (or DIAGRAM.mmd) entries following this skill's templates. The updates are automatic and don't require explicit skill invocation — agents reference the format directly.

package/ftm-intent.yml

@@ -0,0 +1,2 @@
+name: ftm-intent
+description: Manages the hierarchical INTENT.md documentation layer — root index with architecture decisions and module map, plus per-module INTENT.md files with function-level entries (does/why/relationships/decisions). Use when creating or updating intent documentation, bootstrapping a new project's intent layer, or when user says "update intent", "document intent", "ftm-intent", "what does this function do". Auto-invoked by ftm-executor after every commit to keep intent documentation in sync with code changes.

package/ftm-map.yml

@@ -0,0 +1,2 @@
+name: ftm-map
+description: Persistent code knowledge graph powered by tree-sitter and SQLite with FTS5 full-text search. Builds structural dependency graphs, enables blast radius analysis, dependency chain queries, and keyword-based code search. Use when the user asks "what breaks if I change X", "what depends on Y", "blast radius of Z", "where do we handle auth", "map this codebase", "index this project", "what calls function X", "show dependencies for Y". Also triggered by ftm-intent and ftm-diagram for graph-powered view generation. Triggers on "blast radius", "what breaks", "what calls", "what depends on", "where do we", "map codebase", "index", "code graph", "dependency chain", "ftm-map".