forge-orkes 0.1.0

package/template/.claude/skills/auditing/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: auditing
+description: "Use after verifying passes to assess overall application health before milestone completion. Runs security audit (10 categories) and architecture audit (scaling, maintainability, code health). This is the pre-release gate — it answers 'is this codebase healthy enough to ship?'"
+---
+
+# Auditing: Health Audit Before Milestone Completion
+
+You are the pre-release gate. After `verifying` confirms the work delivers what was promised, you assess whether the codebase is healthy enough to ship. Two parallel audits — security and architecture — produce a structured health report that determines whether the milestone can complete.
+
+## When to Trigger
+
+- **Automatically** after `verifying` returns a PASSED verdict (Standard and Full tiers)
+- **On-demand** at any time via user request
+
+## Process Overview
+
+1. Read project context (`.forge/project.yml`) to determine tech stack
+2. Scope the audit — glob all source files, summarize what will be scanned
+3. Spawn two parallel subagents: Security Audit + Architecture Audit
+4. Collect results, score per-category, determine overall status
+5. Write health report to `.forge/audits/milestone-{id}-health-report.md`
+6. Route based on results: healthy → complete, issues → user decides
+
+## Step 1: Read Context
+
+```
+Read: .forge/project.yml → tech stack, framework, database, dependencies
+Read: .forge/state/milestone-{id}.yml → milestone ID and name
+Read: .forge/constitution.md → active architectural gates (if exists)
+```
+
+Determine which security categories apply based on the tech stack. For example:
+- No database → SQL/NoSQL Injection is N/A
+- No frontend → XSS Prevention is N/A
+- No CI/CD config → Pipeline Security is N/A
+
+## Step 2: Scope the Audit
+
+```
+Glob: src/**/*.{ts,tsx,js,jsx,py,go,rs,java} (adapt to project language)
+Glob: **/*.env*, **/docker-compose*, **/.github/workflows/*
+Glob: **/next.config*, **/vite.config*, **/webpack.config*
+```
+
+Present scope summary to user:
+*"Health audit scope: {N} source files, {N} config files. Scanning for security vulnerabilities (10 categories) and architectural health (4 dimensions). This will take a moment."*
+
+Build explicit file lists for each subagent — pass file paths, not globs, so nothing is missed.
+
+## Step 3: Spawn Parallel Audits
+
+Spawn both audits as fresh-context subagents. Each receives:
+- The explicit file list for their scope
+- The tech stack from `project.yml`
+- Their specific audit instructions (below)
+
+### Part 1: Security Audit (subagent)
+
+Spawn a security auditor agent with a fresh context window.
+
+**10 Security Categories:**
+
+| # | Category | What It Checks |
+|---|----------|---------------|
+| 1 | Authentication & Authorization | Every endpoint has auth middleware; role checks before data access |
+| 2 | Data Scoping / Tenant Isolation | Queries scoped to correct user/tenant; no cross-tenant data leaks |
+| 3 | Input Validation | Request bodies/params validated before use in queries or logic |
+| 4 | Error Information Leakage | No stack traces, DB schemas, or internal details in API responses |
+| 5 | XSS Prevention | No unsanitized user content injected into DOM |
+| 6 | SQL/NoSQL Injection | All queries use parameterized placeholders, no string interpolation |
+| 7 | Secrets Management | No hardcoded keys/tokens; `.env` in `.gitignore`; `process.env` usage |
+| 8 | CORS Policy | No wildcard `*` origins in production; appropriate method restrictions |
+| 9 | HTTP Security Headers | CSP, X-Frame-Options, HSTS, X-Content-Type-Options, Referrer-Policy |
+| 10 | CI/CD Pipeline Security | Secrets via secrets context, not hardcoded in workflow files |
+
+**Agent behavior rules:**
+- Read every file in the provided list. No sampling or skipping.
+- Every finding must have: file path, line number, what's wrong, severity, remediation.
+- Understand context before flagging — read surrounding code, check for middleware, wrappers, and higher-order protections.
+- Document intentionally public endpoints; don't flag them as vulnerabilities.
+- Severity is firm: `critical` = exploitable vulnerability, `warning` = defense-in-depth gap, `info` = observation.
+- Prefer false negatives over false positives — only flag what you're confident about.
+- Categories that don't apply to this project's stack → mark as N/A with brief explanation.
+
+**Project adaptation:** Adapt checks to the detected stack:
+- Express vs Next.js vs Fastify endpoint patterns
+- PostgreSQL vs MongoDB vs SQLite query patterns
+- GitHub Actions vs GitLab CI vs other CI systems
+- React vs Vue vs Svelte frontend patterns
+
+**Output format** (return to orchestrator):
+
+```yaml
+security_audit:
+  files_scanned: N
+  categories:
+    - id: 1
+      name: "Authentication & Authorization"
+      status: passed | warning | critical | na
+      findings:
+        - file: "src/api/users.ts"
+          line: 42
+          severity: critical | warning | info
+          issue: "Description of what's wrong"
+          remediation: "How to fix it"
+      notes: "Optional context about intentional decisions"
+```
+
+### Part 2: Architecture Audit (subagent)
+
+Spawn an architecture auditor agent with a fresh context window.
+
+**4 Architecture Dimensions:**
+
+| Dimension | What It Checks |
+|-----------|---------------|
+| **Scalability** | Synchronous blocking calls, missing pagination, unbounded queries, N+1 query patterns, missing caching opportunities, single points of failure, hardcoded limits |
+| **Maintainability** | Code complexity hotspots (files >300 lines, deeply nested logic >4 levels, god components/classes), circular dependencies, duplicated logic that warrants abstraction |
+| **Code Health** | Dead code / unused exports, TODO/FIXME inventory with age, test coverage gaps (untested critical paths), stale/vulnerable dependencies |
+| **Structural Quality** | Separation of concerns violations (business logic in UI layer), inconsistent patterns across similar features, missing error boundaries, API contract consistency |
+
+**Agent behavior rules:**
+- Check actual code, not theoretical concerns.
+- Every finding references specific files with evidence.
+- Severity: `critical` = architectural debt that will cause production issues or block future work, `warning` = quality concern worth addressing, `info` = improvement opportunity.
+- Respect existing ADRs in `.forge/decisions/` — don't flag intentional architectural choices as issues.
+- Respect constitutional articles in `.forge/constitution.md` — if the constitution permits a pattern, don't flag it.
+
+**Output format** (return to orchestrator):
+
+```yaml
+architecture_audit:
+  files_scanned: N
+  dimensions:
+    - name: "Scalability"
+      status: passed | warning | critical
+      findings:
+        - file: "src/api/products.ts"
+          line: 87
+          severity: critical | warning | info
+          issue: "Unbounded query with no pagination"
+          remediation: "Add limit/offset parameters"
+    - name: "Maintainability"
+      status: passed | warning | critical
+      findings: []
+    - name: "Code Health"
+      status: passed | warning | critical
+      findings: []
+    - name: "Structural Quality"
+      status: passed | warning | critical
+      findings: []
+```
+
+## Step 4: Score Results
+
+After both subagents return, compute scores.
+
+**Per-category scoring:**
+
+| Status | Meaning |
+|--------|---------|
+| `passed` | No issues found |
+| `warning` | Non-critical issues (info-level also maps here) |
+| `critical` | Real vulnerabilities or architectural blockers |
+| `na` | Category doesn't apply to this project |
+
+**Overall status:**
+
+| Overall | Condition |
+|---------|-----------|
+| `passed` | ALL categories and dimensions passed or N/A |
+| `warnings_only` | One or more warnings, zero critical |
+| `issues_found` | One or more critical findings |
+
+## Step 5: Write Health Report
+
+Create `.forge/audits/` directory if needed. Write to `.forge/audits/milestone-{id}-health-report.md`.
+
+**YAML frontmatter:**
+
+```yaml
+---
+milestone_id: {id}
+milestone_name: "{name}"
+audited: "{ISO 8601 timestamp}"
+status: passed | warnings_only | issues_found
+security:
+  status: passed | warnings_only | issues_found
+  categories_passed: N
+  categories_warning: N
+  categories_critical: N
+  categories_na: N
+architecture:
+  status: passed | warnings_only | issues_found
+  scalability: passed | warning | critical
+  maintainability: passed | warning | critical
+  code_health: passed | warning | critical
+  structural_quality: passed | warning | critical
+total_files_scanned: N
+---
+```
+
+**Body structure:**
+
+```markdown
+# Health Audit Report: {milestone name}
+
+## Executive Summary
+{1-3 sentences: overall health assessment, key findings, recommendation}
+
+## Security Findings
+
+### Category 1: Authentication & Authorization — {STATUS}
+| File | Line | Severity | Issue | Remediation |
+|------|------|----------|-------|-------------|
+| ... | ... | ... | ... | ... |
+
+{Repeat for each category. N/A categories get a single line: "N/A — {reason}"}
+
+## Architecture Findings
+
+### Scalability — {STATUS}
+| File | Line | Severity | Issue | Remediation |
+|------|------|----------|-------|-------------|
+| ... | ... | ... | ... | ... |
+
+{Repeat for each dimension}
+
+## Public Endpoints
+{List of intentionally public endpoints documented during security audit}
+
+## Files Scanned
+{Count and list of all files scanned across both audits}
+```
+
+**Health trend tracking:** If a previous audit exists for an earlier milestone (check `.forge/audits/` for prior reports), compare results and note improvements or regressions in the executive summary.
+
+## Step 6: Route Based on Results
+
+### HEALTHY (all passed)
+
+Update `.forge/state/milestone-{id}.yml`:
+- Set `current.status` to `refactoring`
+
+Present to user:
+*"Health audit passed. No security vulnerabilities or architectural concerns found. Moving to refactoring review."*
+
+→ Route to `refactoring` skill.
+
+### NEEDS ATTENTION (critical issues found)
+
+Do NOT mark milestone complete. Present to user:
+
+*"Health audit found critical issues that should be addressed before shipping:"*
+
+Inline the top 3 findings per critical category so the user sees them immediately (don't make them open the report).
+
+Then offer choices:
+
+*"Options:"*
+- **A. Fix critical issues** — return to `planning` in fix mode with findings as requirements
+- **B. Accept risk and continue** — document accepted risks in report, proceed to refactoring review
+
+If user chooses A:
+- Create fix requirements from critical findings
+- Route to `planning` skill in fix mode
+- After fix execution, re-run `auditing` (not full `verifying` — just the audit)
+
+If user chooses B:
+- Append "Accepted Risks" section to the health report with user's acknowledgment
+- Update `.forge/state/milestone-{id}.yml`: set `current.status` to `refactoring`
+- → Route to `refactoring` skill.
+
+### ACCEPTABLE WITH CAVEATS (warnings only)
+
+Present to user:
+
+*"Health audit passed with warnings — no critical issues, but {N} items worth noting. See the full report at `.forge/audits/milestone-{id}-health-report.md`."*
+
+Then offer choices:
+- **A. Continue to refactoring review** — accept warnings as known items
+- **B. Fix warnings** — address before continuing
+
+If user chooses A:
+- Document accepted warnings in report
+- Update `.forge/state/milestone-{id}.yml`: set `current.status` to `refactoring`
+- → Route to `refactoring` skill.
+
+If user chooses B:
+- Create fix requirements from warning findings
+- Route to `planning` in fix mode
+- After fix execution, re-run `auditing`
+
+## Gate Type: Soft Gate
+
+This is a soft gate — critical issues strongly recommend fixing before completion, but the user can accept risk and proceed. Rationale:
+- Some issues may be acceptable known risks for the deployment context
+- Some findings may be false positives despite the conservative flagging approach
+- Non-production or internal tools may have different risk tolerances
+- The user always has final authority over ship decisions
+
+The report documents the decision either way, creating an audit trail.

package/template/.claude/skills/beads-integration/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: beads-integration
+description: "Use when Beads is installed and you want persistent memory across sessions. Trigger when: starting a session on an existing project (bd prime for context), need to find unblocked work (bd ready), completing tasks (bd complete), or managing long-horizon multi-session projects. Requires Beads CLI to be installed."
+---
+
+# Beads Integration (Optional)
+
+Persistent cross-session memory. Only available when Beads is installed.
+
+## Prerequisites
+
+Before using this skill, verify:
+1. Beads CLI installed: `bd --version` (should return version)
+2. Beads initialized in project: `.beads/` directory exists
+3. Forge integration enabled: `settings.json → forge.beads_integration: true`
+
+If not installed, Forge works fine without it using `.forge/state/` + Session Memory.
+
+## Integration Points
+
+### On Session Start: `bd prime`
+
+Run at the beginning of every session:
+
+```bash
+bd prime
+```
+
+This injects ~1-2K tokens of context:
+- Open tasks with zero open blockers
+- Recently closed tasks (last 3)
+- Active blockers and their status
+
+Combine with Forge state: read `.forge/state/milestone-{id}.yml` for workflow position (where `{id}` is the selected milestone), `bd prime` for project-wide context.
+
+### Finding Work: `bd ready`
+
+Instead of manually triaging, query what's available:
+
+```bash
+bd ready                    # All unblocked tasks, sorted by priority
+bd ready --priority 3       # Only priority 3+ tasks
+bd ready --json             # Machine-readable output
+```
+
+Use `bd ready` output to inform which Forge phase/plan to work on next.
+
+### During Work: `bd update`
+
+As you complete Forge tasks, update Beads:
+
+```bash
+bd complete {task-id}       # Mark task done
+bd block {task-id} --by {blocker-id}   # Record a blocker
+bd unblock {task-id}        # Remove a blocker
+```
+
+### Memory Hygiene: `bd compact`
+
+Periodically clean up old completed tasks:
+
+```bash
+bd compact --analyze --json  # See what would be compacted
+bd compact --apply           # Summarize old tasks (30+ days closed)
+```
+
+Compaction replaces detailed task content with LLM-generated summaries, preserving essential context while reducing token cost.
+
+## Forge + Beads Workflow
+
+### Quick Tier
+```
+bd prime → quick-tasking → bd complete → done
+```
+
+### Standard Tier
+```
+bd prime → bd ready (pick task) → researching → discussing → planning → executing → bd complete → verifying → done
+```
+
+### Full Tier
+```
+bd prime → bd ready (pick phase) → researching → discussing → architecting → planning → executing → bd complete → verifying → done
+```
+
+## Syncing State
+
+Forge's `.forge/state/` and Beads' `.beads/` serve different purposes:
+
+| Concern | Forge (state/) | Beads (.beads/) |
+|---------|----------------|-----------------|
+| Current workflow position | ✓ (milestone-{id}.yml: phase, plan, task) | |
+| Global framework patterns | ✓ (index.yml: desire_paths, metrics) | |
+| Locked decisions | ✓ (context.md) | |
+| Project-wide task graph | | ✓ (DAG with dependencies) |
+| Cross-session memory | | ✓ (persists in git) |
+| Task prioritization | | ✓ (5-level priority) |
+| Memory compaction | | ✓ (semantic summarization) |
+
+Both are git-tracked. Both survive session boundaries. They complement each other.
+
+## Creating Beads from Forge Plans
+
+When Forge creates plans with tasks, optionally create corresponding Beads:
+
+```bash
+bd create "Implement login form" --priority 3
+bd create "Add auth API endpoint" --priority 3 --blocked-by {login-form-id}
+```
+
+This gives you the DAG dependency tracking that Forge's flat plan files don't provide.
+
+## Disabling Beads Integration
+
+If you want Forge without Beads:
+
+```json
+{
+  "forge": {
+    "beads_integration": false
+  }
+}
+```
+
+Beads continues working independently. Forge just won't query or update it.

package/template/.claude/skills/debugging/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: debugging
+description: "Use when code isn't working and you need to investigate systematically. Trigger when: tests fail unexpectedly, features don't work as expected, errors are cryptic or intermittent, or you've been stuck for more than 10 minutes. This skill prevents thrashing by enforcing scientific debugging."
+---
+
+# Debugging
+
+Debug systematically. Every hypothesis tested, every dead end recorded.
+
+## The Scientific Method for Bugs
+
+1. **Observe**: What's the actual behavior? (exact error, steps to reproduce, when it started)
+2. **Hypothesize**: Why might this happen? (max 3 hypotheses)
+3. **Predict**: If hypothesis is correct, what should we observe when we test?
+4. **Test**: Run the test. Capture evidence.
+5. **Eliminate**: Does evidence support or refute? Record result.
+6. **Iterate**: Next hypothesis, or refine current one.
+7. **Conclude**: Root cause identified. Fix it.
+
+## Persistent Debug File
+
+Create `.forge/debug/{slug}.md` to survive context resets:
+
+```markdown
+---
+status: gathering | investigating | fixing | verifying | resolved
+trigger: "[exact symptom or error message]"
+created: 2026-02-16T19:00:00Z
+updated: 2026-02-16T19:30:00Z
+---
+
+## Symptoms
+- Expected: [what should happen]
+- Actual: [what actually happens]
+- Error: [exact error message if any]
+- Reproduction: [steps to trigger]
+- Since: [when it broke — commit, change, or "always"]
+
+## Current Focus
+- Hypothesis: [what I'm currently testing]
+- Test: [how I'm testing it]
+- Expecting: [what result means]
+
+## Hypotheses
+
+### H1: [Specific, falsifiable hypothesis]
+- Predict: [If true, we'd see...]
+- Test: [How to test]
+- Result: SUPPORTED | REFUTED | INCONCLUSIVE
+- Evidence: [What we observed]
+
+### H2: [Second hypothesis]
+...
+
+## Eliminated
+- [H1]: Refuted because [evidence]. Timestamp: [when]
+
+## Evidence Log
+- [timestamp]: Checked [what]. Found [what]. Implies [what].
+
+## Root Cause
+[Empty until found]
+
+## Fix
+[Empty until applied]
+
+## Verification
+[Empty until fix is verified]
+```
+
+### Update Rules
+- **Status**: Overwrite (phase transitions only)
+- **Current Focus**: Overwrite (before every action)
+- **Symptoms**: Immutable after gathering phase
+- **Eliminated**: Append only (prevents re-investigating dead ends)
+- **Evidence Log**: Append only
+
+## Investigation Techniques
+
+Use these in order of effectiveness:
+
+### 1. Read the Error (seriously)
+Read the ENTIRE error message, stack trace, and surrounding log output. Most bugs are explained by the error — we just don't read carefully enough.
+
+### 2. Binary Search
+Cut the problem space in half. If a function has 10 steps, test after step 5. If it works, bug is in steps 6-10. Repeat.
+
+### 3. Minimal Reproduction
+Strip away everything until only the bug remains. Remove middleware, simplify data, use hardcoded values. The smaller the reproduction, the clearer the cause.
+
+### 4. Differential Debugging
+What changed? `git diff`, `git log`, recent dependency updates. If it worked before and doesn't now, something changed.
+
+### 5. Working Backwards
+Start from the wrong output. Trace the data backward through the system: which function produced it? What was its input? Where did that come from?
+
+### 6. Comment Out Everything
+Remove all code. Uncomment one piece at a time. When the bug reappears, you found the culprit.
+
+### 7. Add Observability First
+Before changing behavior, add logging. See what's actually happening before guessing.
+
+### 8. Git Bisect
+If you know it worked at some point: `git bisect start`, `git bisect bad` (current), `git bisect good {hash}` (working version). Git finds the exact breaking commit.
+
+## Cognitive Bias Awareness
+
+Watch for these traps:
+- **Confirmation bias**: Seeking evidence that supports your theory, ignoring counter-evidence
+- **Anchoring**: Fixating on the first theory instead of considering alternatives
+- **Availability bias**: Blaming the last thing you changed, even if unrelated
+- **Sunk cost**: Continuing a dead-end investigation because you've spent time on it
+
+Counter-measure: After 3 failed hypotheses, step back and re-read symptoms from scratch.
+
+## When to Escalate
+
+After 5 hypotheses tested without finding root cause:
+1. Document everything in debug file (what's tried, what's eliminated)
+2. Mark as `[NEEDS PAIR DEBUGGING]` in `.forge/state/milestone-{id}.yml` blockers
+3. The debug file saves the next person hours of re-investigation
+
+## Resolution
+
+When root cause found:
+1. Fix the issue
+2. Add a test that catches this specific bug (regression test)
+3. Commit: `fix({scope}): {description of root cause and fix}`
+4. Move debug file to `.forge/debug/resolved/`
+5. Update `.forge/state/milestone-{id}.yml` — remove from blockers

package/template/.claude/skills/designing/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: designing
+description: "Use when building UI: component selection, visual design, responsive layouts, accessibility, design system consistency. Trigger whenever the deliverable includes visible UI. Reads design system config from .forge/project.yml and component mappings from .forge/design-system.md."
+---
+
+# Designing
+
+Build consistent, accessible UIs by using the project's design system, not fighting it.
+
+## Step 1: Load Design System Config
+
+Read the project's design system configuration:
+
+```
+Read: .forge/project.yml → design_system section
+Read: .forge/design-system.md (component mapping table)
+```
+
+If neither exists, this project hasn't been initialized with a design system. Ask the user:
+- *"This project doesn't have a design system configured. Would you like to set one up now, or proceed without design system enforcement?"*
+
+If `design_system.library` is `none`, skip component enforcement and focus on general design principles (accessibility, responsiveness, loading states).
+
+## Step 2: Component Mapping
+
+The component mapping table in `.forge/design-system.md` is the source of truth. It maps UI needs to specific components from the project's library.
+
+**When building any UI element**, check the mapping table first:
+1. Look up the UI need (data table, modal, dropdown, etc.)
+2. Use the mapped component with the documented props
+3. If the UI need isn't in the table → check the library's docs → add to the table
+
+**Never build custom HTML/CSS for patterns the design system provides.** This is the single most important rule.
+
+## Step 3: Style Rules
+
+These rules adapt based on the configured design system:
+
+1. **Use the design system's tokens, NOT custom CSS values**
+   - Read `design_system.theme_approach` from project.yml
+   - Bad: `style={{color: '#3B82F6', padding: '12px'}}`
+   - Good: Use the library's utility classes or theme tokens
+
+2. **Use design system components, NOT raw HTML**
+   - Bad: `<table><thead><tr><th>` for data display
+   - Good: The library's table/data grid component
+   - Bad: `<div className="modal-overlay">` with absolute positioning
+   - Good: The library's dialog/modal component
+
+3. **Use the configured icon set**
+   - Read `design_system.icon_set` from project.yml
+   - Use only icons from this set for consistency
+
+4. **Use the configured layout system**
+   - Read `design_system.layout_system` from project.yml
+   - Use its grid/flex utilities for responsive layouts
+   - Never hardcode pixel widths for responsive layouts
+
+5. **Theme customization goes in theme files, not inline**
+   - Override theme variables in the designated theme config
+   - Never scatter theme overrides across component files
+
+## Step 4: General Design Principles
+
+These apply regardless of which design system is used (or if none is used).
+
+### Accessibility
+- Every interactive element needs a label (visible or `aria-label`)
+- Color is never the only indicator (use icons + color)
+- Keyboard navigation works for all interactive elements
+- Focus indicators are visible
+- Most design system components handle a11y by default — don't override it
+
+### Responsive Design
+- Mobile-first: design for small screens, enhance for large
+- Use the layout system's breakpoints
+- Test at 320px, 768px, 1024px, 1440px widths
+- Tables should scroll horizontally on mobile
+
+### Loading States
+- Always show loading indicators for async operations
+- Use skeleton loaders or spinners during data fetch
+- Disable submit buttons while processing
+
+### Form Patterns
+- Labels above inputs, not beside (better for mobile and a11y)
+- Validation messages appear near the relevant field
+- Submit buttons show loading state during submission
+- Forms use the design system's form components
+
+## Step 5: Output Checklist
+
+- [ ] All UI elements checked against `.forge/design-system.md` mapping table
+- [ ] No custom HTML/CSS for patterns the design system provides
+- [ ] Theme tokens used for colors, spacing, typography
+- [ ] Configured icon set used for all icons
+- [ ] Responsive layout using configured layout system
+- [ ] Keyboard navigation works
+- [ ] Loading states present for all async operations
+- [ ] Forms use proper labels and validation messages
+
+## Creating a New Design System Config
+
+When setting up a design system during project init (or later), follow this process:
+
+1. **Research the library**: Use `researching` skill to pull component docs
+2. **Build the mapping table**: Create `.forge/design-system.md` with this structure:
+
+```markdown
+# Design System: {Library Name}
+
+Docs: {docs_url}
+
+## Component Mapping
+
+| UI Need | Component | Key Props | Example |
+|---------|-----------|-----------|---------|
+| Data table | `<ComponentName>` | `prop1`, `prop2` | `<ComponentName prop1={val} />` |
+| Modal | ... | ... | ... |
+| Dropdown | ... | ... | ... |
+| ... | ... | ... | ... |
+
+## Style Rules
+
+{Library-specific style rules, e.g., utility classes, theme tokens}
+
+## Icon Reference
+
+{How to use icons from the configured icon set}
+```
+
+3. **Validate with user**: Present the mapping and ask if anything is missing or wrong.
+
+Example configs for common libraries are available in `.forge/templates/design-systems/` as starting points.