forge-orkes 0.1.0

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

@@ -0,0 +1,201 @@
+---
+name: verifying
+description: "Use when work is complete and you need to prove it actually works. Trigger after execution: does the code meet original requirements? Not 'did we complete tasks' but 'does it work?' This skill enforces goal-backward verification with 3 levels: Observable Truths, Artifacts, and Key Links."
+---
+
+# Verifying
+
+Prove completed work actually delivers what was promised. Task completion ≠ goal achievement.
+
+## Core Question
+
+Don't ask: "Did we complete all the tasks?"
+Ask: "Does the user get what they were promised?"
+
+## 3-Level Goal-Backward Verification
+
+### Level 1: Observable Truths
+
+Read the plan's `must_haves.truths`. For each truth:
+
+1. Design a test (automated or manual) that proves/disproves it
+2. Run the test
+3. Record result: **VERIFIED** | **FAILED** | **UNCERTAIN**
+
+```markdown
+| Truth | Test | Result |
+|-------|------|--------|
+| User can see their profile | Navigate to /profile, check render | VERIFIED |
+| User can edit their bio | Click edit, type, save, verify persistence | VERIFIED |
+| Profile photo uploads correctly | Upload image, check display | FAILED — 413 error on large files |
+```
+
+### Level 2: Artifacts (Exists → Substantive → Wired)
+
+Read the plan's `must_haves.artifacts`. For each artifact:
+
+| Check | Question | Pass Criteria |
+|-------|----------|---------------|
+| **Exists** | Does the file exist? | File present at specified path |
+| **Substantive** | Is it real code, not a stub? | Exceeds min_lines, no placeholder text, real logic |
+| **Wired** | Is it imported and used by other code? | Has importers, called in production paths |
+
+```markdown
+| Artifact | Exists | Substantive | Wired | Status |
+|----------|--------|-------------|-------|--------|
+| src/components/Profile.tsx | ✓ | ✓ (87 lines) | ✓ (imported in routes) | VERIFIED |
+| src/api/users/[id].ts | ✓ | ✓ (43 lines) | ✓ (called by Profile) | VERIFIED |
+| src/hooks/useProfile.ts | ✓ | ✗ (returns {}) | - | STUB |
+```
+
+### Stub Detection Red Flags
+
+Watch for these patterns that indicate stubs, not real implementations:
+
+**React components:**
+- `<div>Component</div>` or `<div>Placeholder</div>`
+- `onClick={() => {}}` (empty handler)
+- `onChange={() => console.log()}` (logging-only handler)
+- Hardcoded data instead of API calls
+
+**API endpoints:**
+- `return Response.json({ message: "Not implemented" })`
+- Empty arrays without database queries
+- TODO comments in response path
+
+**Wiring:**
+- `fetch()` without await/then
+- Query without returning result
+- Form with only `preventDefault`
+
+### Level 3: Key Links
+
+Read the plan's `must_haves.key_links`. Verify each connection:
+
+| Pattern | How to Verify |
+|---------|---------------|
+| Component → API | Find fetch/axios call in component pointing to API route |
+| API → Database | Find ORM/query call in API handler returning data |
+| Form → Handler | Find onSubmit with API call and response handling |
+| State → Render | Find state variable used in JSX (not just declared) |
+
+```markdown
+| From | To | Via | Pattern | Status |
+|------|----|-----|---------|--------|
+| Profile.tsx | /api/users/[id] | fetch in useEffect | fetch.*api/users | VERIFIED |
+| ProfileForm.tsx | /api/users/[id] | PUT on submit | method.*PUT | VERIFIED |
+```
+
+## Anti-Pattern Scan
+
+After 3-level verification, scan for common issues:
+
+- [ ] No `TODO` or `FIXME` in production code paths
+- [ ] No `console.log` as error handling
+- [ ] No empty catch blocks
+- [ ] No hardcoded credentials or secrets
+- [ ] No commented-out code blocks
+
+## Requirements Coverage
+
+Cross-reference verified work against `.forge/requirements.yml`:
+
+```markdown
+| Requirement | Status | Evidence |
+|-------------|--------|----------|
+| FR-001 | Verified | Profile renders, tests pass |
+| FR-002 | Verified | Edit flow works end-to-end |
+| FR-003 | Partial | Upload works for small files, fails > 5MB |
+```
+
+## Verdict
+
+Based on all verification levels:
+
+### PASSED
+All truths verified, all artifacts substantive and wired, all key links connected, requirements covered.
+→ Route to `auditing` skill for health audit before milestone completion.
+
+### GAPS FOUND
+Some truths failed or artifacts are stubs.
+→ Document gaps in YAML format:
+
+```yaml
+gaps:
+  - truth: "Profile photo uploads correctly"
+    status: failed
+    reason: "413 error on files > 5MB"
+    artifacts:
+      - path: "src/api/upload.ts"
+        issue: "No file size validation or chunked upload"
+    fix_needed:
+      - "Add file size validation with user-friendly error"
+      - "Implement chunked upload for large files"
+```
+
+→ Return to `planning` skill in gap-closure mode.
+
+### HUMAN VERIFICATION NEEDED
+Some items can't be verified automatically (visual appearance, real-time behavior, external service integration).
+→ List items for user to verify manually:
+
+```markdown
+## Human Verification Items
+1. [ ] Visual: Profile layout matches design on mobile
+2. [ ] Real-time: Notifications appear within 2 seconds
+3. [ ] External: Email sends correctly via SendGrid
+```
+
+## Re-Verification Mode
+
+When re-verifying after gap closure:
+1. Load previous verification results
+2. Full 3-level check on previously failed items
+3. Quick regression check on previously passed items (exists + basic sanity)
+4. Merge results and issue updated verdict
+
+## Desire Paths Retrospective
+
+After completing verification (PASSED or GAPS FOUND), do a quick retrospective on framework usage patterns. This takes 1-2 minutes and feeds the framework's self-improvement loop.
+
+### Collect Signals
+
+Review the current session and update `.forge/state/index.yml → desire_paths` (desire paths are global, not per-milestone):
+
+**1. Deviation patterns**: Read `.forge/state/milestone-{id}.yml → deviations` from this session. Are any repeating?
+- Same Rule 1 fix in multiple places → maybe the plan template should include this check
+- Same Rule 2 addition everywhere → maybe the constitution needs a new article
+- Same Rule 3 issue → maybe the project setup is missing something
+
+**2. Tier overrides**: Did the user override tier detection this session? Log what was detected vs. chosen. Repeated overrides mean the detection heuristics are wrong.
+
+**3. Skipped steps**: Did the user ask to skip any workflow steps? (e.g., "skip the constitution check", "don't need a full research phase"). Repeated skips mean the step adds friction without value for this project type.
+
+**4. Recurring friction**: Did the same problem come up that appeared in previous sessions? Check previous `desire_paths` entries. Increment occurrence counts.
+
+**5. Agent struggles**: Did any agent need multiple attempts or human intervention to complete a task? Log the task type and failure pattern.
+
+**6. User corrections**: Did the user correct the same thing multiple times? (e.g., "remember to use the Card component, not a div", "always add error boundaries"). These are implicit rules that should become explicit.
+
+### Surface Recommendations
+
+When any pattern reaches **3+ occurrences**, surface it to the user:
+
+*"I've noticed a recurring pattern: [{description}] has come up {N} times now. This suggests we should evolve the framework. Options:"*
+
+| Pattern Type | Suggested Evolution |
+|-------------|-------------------|
+| Repeated deviations | Add pre-check to planning skill, or new constitutional article |
+| Tier overrides | Adjust detection heuristics in forge skill |
+| Skipped steps | Make step optional for this project type, or merge into another step |
+| Recurring friction | Add specific guidance to relevant skill, or create a new template |
+| Agent struggles | Add examples or anti-patterns to the skill that handles this task |
+| User corrections | Add as a rule to constitution, context.md, or the relevant skill |
+
+**Concrete actions the user can approve:**
+- *"Should I add 'always use Card component for content containers' to the design-system.md?"*
+- *"Should I add a null-check verification step to the planning template?"*
+- *"Should I make the research phase optional for Standard tier in this project?"*
+- *"Should I add a new constitutional article: 'Error Boundaries Required'?"*
+
+Only suggest changes when there's clear evidence (3+ occurrences). One-off issues are noise, not signal.

package/template/.forge/templates/constitution.md

@@ -0,0 +1,123 @@
+# Project Constitution
+
+Immutable architectural gates. Every plan and execution must satisfy active articles.
+If an article is violated, planning stops until the gate is re-cleared or the article is formally amended.
+
+During project init, select which articles apply. Delete or comment out articles that don't apply.
+You can also add project-specific articles at the end.
+
+---
+
+## Code Quality Articles
+
+_Most projects benefit from these. Recommended as defaults._
+
+### Article I: Library-First
+
+Prefer proven libraries over custom implementations. Only build custom when no adequate library exists or integration cost exceeds building cost.
+
+**Gate:**
+- [ ] Checked ecosystem for existing solutions before planning custom code
+- [ ] If custom code planned, documented WHY libraries were rejected
+
+### Article II: Test-First
+
+Tests are written before or alongside implementation, never as an afterthought. Tests must fail before code makes them pass.
+
+**Gate:**
+- [ ] Test strategy defined before implementation begins
+- [ ] Acceptance criteria are testable (Given/When/Then format)
+
+### Article III: Simplicity
+
+The simplest solution that meets requirements wins. Complexity requires documented justification with alternatives considered.
+
+**Gate:**
+- [ ] No speculative features (YAGNI)
+- [ ] No premature abstraction
+- [ ] Complexity justified in writing if introduced
+
+### Article IV: Consistency
+
+New code follows existing project patterns. Deviations from established conventions require rationale.
+
+**Gate:**
+- [ ] Follows existing naming conventions
+- [ ] Matches existing file structure patterns
+- [ ] Uses existing utilities rather than creating duplicates
+
+---
+
+## Design & UI Articles
+
+_Enable if the project has a user interface. Requires design system configuration in project.yml._
+
+### Article V: Design System Fidelity
+
+UI implementations use the project's design system components exclusively. No custom HTML/CSS for patterns the design system already provides. Component mapping is defined in `.forge/design-system.md`.
+
+**Gate:**
+- [ ] All UI elements mapped to design system components (see `.forge/design-system.md`)
+- [ ] No custom markup replacing design system primitives
+- [ ] Theme tokens used instead of hardcoded colors/spacing
+- [ ] Configured icon set used consistently
+
+_Note: If `design_system.library` is `none` in project.yml, this article is automatically inactive._
+
+---
+
+## Security & Data Articles
+
+_Enable if the project handles authentication, user data, or external APIs._
+
+### Article VI: Security by Default
+
+Authentication, authorization, input validation, and secret management are never optional. Security is a requirement, not a feature.
+
+**Gate:**
+- [ ] Secrets stored in environment variables, never in code
+- [ ] User input validated and sanitized
+- [ ] Authentication/authorization checked before data access
+
+---
+
+## Architecture Articles
+
+_Enable based on project complexity and team needs._
+
+### Article VII: Integration-First
+
+Components are tested with real dependencies (real database, real API calls) before mocking is introduced. Mocks are a last resort, not a first choice.
+
+**Gate:**
+- [ ] Integration tests planned before unit tests
+- [ ] Mocks used only for external services outside our control
+
+### Article VIII: Documentation-Driven
+
+Architectural decisions, API contracts, and non-obvious behavior are documented where the code lives, not in separate docs that drift.
+
+**Gate:**
+- [ ] Key decisions documented as ADRs or inline comments with rationale
+- [ ] API contracts defined before implementation
+
+### Article IX: Observability
+
+Production code must be debuggable. Logging, error reporting, and health checks are first-class concerns.
+
+**Gate:**
+- [ ] Error handling includes meaningful messages (not empty catches)
+- [ ] Key operations have logging or tracing
+- [ ] Failure modes are documented
+
+---
+
+## Project-Specific Articles
+
+_Add custom articles below during project init. Follow the same format: rule + gate checkboxes._
+
+---
+
+## Amending the Constitution
+
+Articles can be amended only by explicit user decision during a discuss phase. Amendments are recorded in `.forge/context.md` with rationale. No agent may unilaterally override a constitutional article.

package/template/.forge/templates/context.md

@@ -0,0 +1,53 @@
+# Locked Context
+
+Created during the discuss phase. This document is a contract between the user and all downstream agents.
+
+**Rules:**
+- **Locked Decisions** → MUST be implemented exactly as stated. No alternatives. No "better" solutions.
+- **Deferred Ideas** → MUST NOT appear in plans, tasks, or code. Not even as TODOs.
+- **Discretion Areas** → Agent uses judgment. Research the options, pick the best, document why.
+
+---
+
+## Locked Decisions
+
+<!-- Add one per line. Be specific. Include the WHY if it helps agents understand intent. -->
+
+- **[Topic]**: [Decision]. Reason: [Why this was chosen]
+- **[Topic]**: [Decision]. Reason: [Why this was chosen]
+
+## Deferred Ideas
+
+<!-- These are explicitly out of scope. Agents must not implement or plan for these. -->
+
+- [Idea] — Deferred because: [reason]. Revisit: [when]
+- [Idea] — Deferred because: [reason]. Revisit: [when]
+
+## Discretion Areas
+
+<!-- Agent picks the best approach. Document the choice and rationale after deciding. -->
+
+- [Topic]: [Options under consideration]. Agent should research and recommend.
+- [Topic]: [Options under consideration]. Agent should research and recommend.
+
+## Carried Forward
+
+<!-- Knowledge from a previous framework or session that didn't map cleanly to Forge files. -->
+<!-- Review during planning — some items may become requirements, decisions, or deferrals. -->
+
+## Needs Resolution
+
+<!-- Discrepancies found during brownfield init or absorption that need user input. -->
+<!-- BLOCKING: Planning cannot proceed until all items here are resolved or moved to another section. -->
+<!-- When resolved, move item to Locked Decisions, Deferred Ideas, or delete with rationale. -->
+
+- [ ] [Discrepancy description] — Found: [what code shows]. Documented: [what old docs said]. Action needed: [question for user]
+
+---
+
+## Amendment Log
+
+<!-- If a locked decision changes, record it here with date and rationale. -->
+
+| Date | Change | Rationale | Approved By |
+|------|--------|-----------|-------------|

package/template/.forge/templates/design-systems/material-ui.md

@@ -0,0 +1,44 @@
+# Design System: Material UI (MUI)
+
+Docs: https://mui.com/material-ui/
+
+## Component Mapping
+
+| UI Need | Component | Key Props | Example |
+|---------|-----------|-----------|---------|
+| Data table | `<DataGrid>` | `rows`, `columns`, `pageSizeOptions` | `<DataGrid rows={data} columns={cols} pageSizeOptions={[10, 25]} />` |
+| Modal dialog | `<Dialog>` | `open`, `onClose` | `<Dialog open={show} onClose={() => setShow(false)}><DialogTitle>Confirm</DialogTitle><DialogContent>...</DialogContent></Dialog>` |
+| Dropdown/select | `<Select>` | `value`, `onChange`, `label` | `<FormControl><InputLabel>Role</InputLabel><Select value={val} onChange={e => setVal(e.target.value)}><MenuItem value="admin">Admin</MenuItem></Select></FormControl>` |
+| Autocomplete | `<Autocomplete>` | `options`, `value`, `onChange`, `renderInput` | `<Autocomplete options={items} renderInput={p => <TextField {...p} />} />` |
+| Toast/snackbar | `<Snackbar>` + `<Alert>` | `open`, `onClose`, `severity` | `<Snackbar open={show}><Alert severity="success">Saved</Alert></Snackbar>` |
+| Button | `<Button>` | `variant`, `color`, `onClick`, `startIcon` | `<Button variant="contained" startIcon={<SaveIcon />} onClick={save}>Save</Button>` |
+| Text input | `<TextField>` | `value`, `onChange`, `label`, `variant` | `<TextField value={text} onChange={e => setText(e.target.value)} label="Name" />` |
+| Number input | `<TextField>` | `type="number"`, `inputProps` | `<TextField type="number" inputProps={{min: 0}} />` |
+| Date picker | `<DatePicker>` | `value`, `onChange` | `<DatePicker value={date} onChange={setDate} />` (requires @mui/x-date-pickers) |
+| Sidebar/drawer | `<Drawer>` | `open`, `onClose`, `anchor` | `<Drawer open={show} onClose={() => setShow(false)} anchor="right">...</Drawer>` |
+| Tabs | `<Tabs>` + `<Tab>` | `value`, `onChange` | `<Tabs value={tab} onChange={(e,v) => setTab(v)}><Tab label="Tab 1" /></Tabs>` |
+| Accordion | `<Accordion>` | `expanded`, `onChange` | `<Accordion expanded={open}><AccordionSummary>Title</AccordionSummary><AccordionDetails>Content</AccordionDetails></Accordion>` |
+| App bar | `<AppBar>` + `<Toolbar>` | `position` | `<AppBar position="static"><Toolbar>...</Toolbar></AppBar>` |
+| Breadcrumb | `<Breadcrumbs>` | `separator` | `<Breadcrumbs><Link>Home</Link><Typography>Current</Typography></Breadcrumbs>` |
+| Progress bar | `<LinearProgress>` | `variant`, `value` | `<LinearProgress variant="determinate" value={50} />` |
+| Chip/tag | `<Chip>` | `label`, `color`, `onDelete` | `<Chip label="Active" color="primary" />` |
+| Card | `<Card>` | — | `<Card><CardContent><Typography>...</Typography></CardContent><CardActions>...</CardActions></Card>` |
+| Skeleton loader | `<Skeleton>` | `variant`, `width`, `height` | `<Skeleton variant="rectangular" width="100%" height={40} />` |
+| Spinner | `<CircularProgress>` | `size`, `color` | `<CircularProgress size={40} />` |
+
+## Style Rules
+
+- **Theme tokens**: Use MUI's `sx` prop with theme tokens (`sx={{ color: 'primary.main', p: 3 }}`)
+- **Layout**: Use MUI Grid (`<Grid container spacing={2}><Grid item xs={12} md={6}>`)
+- **Spacing**: Theme-based spacing (`sx={{ p: 2, m: 1, gap: 2 }}` where 1 unit = 8px)
+- **Colors**: Always reference theme palette (`primary.main`, `error.light`, `text.secondary`)
+- **Theme customization**: Use `createTheme()` and `ThemeProvider`, never inline color values
+- **Styled components**: Use `styled()` utility or `sx` prop, avoid external CSS files
+
+## Icon Reference
+
+Material Icons: `import { IconName } from "@mui/icons-material"`
+
+Common: `Save`, `Delete`, `Edit`, `Add`, `Search`, `Close`, `Check`, `Person`, `Settings`, `Download`, `Upload`, `Refresh`, `FilterList`, `Sort`, `Visibility`, `VisibilityOff`
+
+Full list: https://mui.com/material-ui/material-icons/

package/template/.forge/templates/design-systems/primereact.md

@@ -0,0 +1,46 @@
+# Design System: PrimeReact
+
+Docs: https://primereact.org
+
+## Component Mapping
+
+| UI Need | Component | Key Props | Example |
+|---------|-----------|-----------|---------|
+| Data table | `<DataTable>` | `value`, `paginator`, `sortMode`, `selectionMode` | `<DataTable value={data} paginator rows={10} sortMode="multiple" />` |
+| Sortable columns | `<Column>` | `field`, `header`, `sortable`, `filter` | `<Column field="name" header="Name" sortable filter />` |
+| Row selection | DataTable | `selectionMode="checkbox"`, `selection`, `onSelectionChange` | `<DataTable selectionMode="checkbox" selection={selected} onSelectionChange={e => setSelected(e.value)} />` |
+| Modal dialog | `<Dialog>` | `visible`, `onHide`, `header`, `modal` | `<Dialog visible={show} onHide={() => setShow(false)} header="Confirm" modal />` |
+| Dropdown/select | `<Dropdown>` | `value`, `onChange`, `options`, `optionLabel` | `<Dropdown value={val} onChange={e => setVal(e.value)} options={items} optionLabel="name" />` |
+| Multi-select | `<MultiSelect>` | `value`, `onChange`, `options`, `display` | `<MultiSelect value={vals} onChange={e => setVals(e.value)} options={items} display="chip" />` |
+| Toast | `<Toast>` + ref | `ref`, then `toast.current.show({severity, summary, detail})` | `<Toast ref={toast} />` |
+| Button | `<Button>` | `label`, `icon`, `onClick`, `severity`, `outlined` | `<Button label="Save" icon="pi pi-check" severity="success" />` |
+| Text input | `<InputText>` | `value`, `onChange`, `placeholder` | `<InputText value={text} onChange={e => setText(e.target.value)} />` |
+| Text area | `<InputTextarea>` | `value`, `onChange`, `rows`, `autoResize` | `<InputTextarea value={text} onChange={e => setText(e.target.value)} autoResize />` |
+| Number input | `<InputNumber>` | `value`, `onValueChange`, `mode`, `min`, `max` | `<InputNumber value={num} onValueChange={e => setNum(e.value)} />` |
+| Date picker | `<Calendar>` | `value`, `onChange`, `showIcon`, `dateFormat` | `<Calendar value={date} onChange={e => setDate(e.value)} showIcon />` |
+| Sidebar/drawer | `<Sidebar>` | `visible`, `onHide`, `position` | `<Sidebar visible={show} onHide={() => setShow(false)} position="right" />` |
+| Tabs | `<TabView>` + `<TabPanel>` | `activeIndex`, `onTabChange` | `<TabView><TabPanel header="Tab 1">Content</TabPanel></TabView>` |
+| Accordion | `<Accordion>` + `<AccordionTab>` | `activeIndex`, `multiple` | `<Accordion multiple><AccordionTab header="Section">Content</AccordionTab></Accordion>` |
+| Menu bar | `<Menubar>` | `model` | `<Menubar model={[{label:'File', items:[{label:'New'}]}]} />` |
+| Breadcrumb | `<BreadCrumb>` | `model`, `home` | `<BreadCrumb model={items} home={{icon:'pi pi-home', url:'/'}} />` |
+| Progress bar | `<ProgressBar>` | `value`, `showValue` | `<ProgressBar value={50} />` |
+| Chip/tag | `<Chip>` | `label`, `icon`, `removable` | `<Chip label="Active" icon="pi pi-check" />` |
+| File upload | `<FileUpload>` | `mode`, `accept`, `maxFileSize` | `<FileUpload mode="basic" accept="image/*" maxFileSize={5000000} />` |
+| Skeleton loader | `<Skeleton>` | `width`, `height`, `shape` | `<Skeleton width="100%" height="2rem" />` |
+| Spinner | `<ProgressSpinner>` | `style`, `strokeWidth` | `<ProgressSpinner style={{width:'50px'}} />` |
+
+## Style Rules
+
+- **Theme tokens**: Use PrimeReact CSS classes (`text-primary`, `p-3`, `surface-card`) not inline styles
+- **Layout**: Use PrimeFlex (`className="grid"` with `col-12 md:col-6 lg:col-3`)
+- **Flex**: `className="flex align-items-center justify-content-between gap-3"`
+- **Spacing**: PrimeFlex utilities (`p-3`, `m-2`, `gap-3`)
+- **Theme customization**: Override in `_variables.scss` or theme config, never inline
+
+## Icon Reference
+
+PrimeIcons: `<i className="pi pi-{name}"></i>` or `icon="pi pi-{name}"` on Button
+
+Common: `pi-check`, `pi-times`, `pi-search`, `pi-plus`, `pi-trash`, `pi-pencil`, `pi-user`, `pi-cog`, `pi-download`, `pi-upload`, `pi-refresh`, `pi-filter`, `pi-sort-alt`, `pi-eye`, `pi-eye-slash`
+
+Full list: https://primereact.org/icons

package/template/.forge/templates/design-systems/shadcn-ui.md

@@ -0,0 +1,47 @@
+# Design System: shadcn/ui
+
+Docs: https://ui.shadcn.com
+
+## Component Mapping
+
+| UI Need | Component | Key Props | Example |
+|---------|-----------|-----------|---------|
+| Data table | `<DataTable>` (custom) | `columns`, `data` | Use TanStack Table + shadcn styling |
+| Modal dialog | `<Dialog>` | `open`, `onOpenChange` | `<Dialog open={show} onOpenChange={setShow}><DialogContent>...</DialogContent></Dialog>` |
+| Dropdown/select | `<Select>` | `value`, `onValueChange` | `<Select value={val} onValueChange={setVal}><SelectTrigger><SelectValue /></SelectTrigger><SelectContent>...</SelectContent></Select>` |
+| Command menu | `<Command>` | — | `<Command><CommandInput /><CommandList><CommandItem>...</CommandItem></CommandList></Command>` |
+| Toast | `useToast()` hook | `toast({ title, description })` | `const { toast } = useToast(); toast({ title: "Saved" })` |
+| Button | `<Button>` | `variant`, `size`, `onClick` | `<Button variant="default" onClick={save}>Save</Button>` |
+| Text input | `<Input>` | `value`, `onChange`, `placeholder` | `<Input value={text} onChange={e => setText(e.target.value)} />` |
+| Text area | `<Textarea>` | `value`, `onChange`, `rows` | `<Textarea value={text} onChange={e => setText(e.target.value)} />` |
+| Date picker | `<DatePicker>` | `date`, `setDate` | `<DatePicker date={date} setDate={setDate} />` |
+| Sidebar/sheet | `<Sheet>` | `open`, `onOpenChange` | `<Sheet open={show} onOpenChange={setShow}><SheetContent>...</SheetContent></Sheet>` |
+| Tabs | `<Tabs>` | `value`, `onValueChange` | `<Tabs value={tab} onValueChange={setTab}><TabsList><TabsTrigger>...</TabsTrigger></TabsList></Tabs>` |
+| Accordion | `<Accordion>` | `type`, `collapsible` | `<Accordion type="multiple"><AccordionItem>...</AccordionItem></Accordion>` |
+| Navigation | `<NavigationMenu>` | — | `<NavigationMenu><NavigationMenuList>...</NavigationMenuList></NavigationMenu>` |
+| Breadcrumb | `<Breadcrumb>` | — | `<Breadcrumb><BreadcrumbList><BreadcrumbItem>...</BreadcrumbItem></BreadcrumbList></Breadcrumb>` |
+| Progress bar | `<Progress>` | `value` | `<Progress value={50} />` |
+| Badge/tag | `<Badge>` | `variant` | `<Badge variant="secondary">Active</Badge>` |
+| Alert | `<Alert>` | `variant` | `<Alert variant="destructive"><AlertTitle>Error</AlertTitle></Alert>` |
+| Card | `<Card>` | — | `<Card><CardHeader><CardTitle>...</CardTitle></CardHeader><CardContent>...</CardContent></Card>` |
+| Checkbox | `<Checkbox>` | `checked`, `onCheckedChange` | `<Checkbox checked={val} onCheckedChange={setVal} />` |
+| Switch | `<Switch>` | `checked`, `onCheckedChange` | `<Switch checked={val} onCheckedChange={setVal} />` |
+| Skeleton loader | `<Skeleton>` | `className` | `<Skeleton className="h-4 w-full" />` |
+| Dropdown menu | `<DropdownMenu>` | — | `<DropdownMenu><DropdownMenuTrigger>...</DropdownMenuTrigger><DropdownMenuContent>...</DropdownMenuContent></DropdownMenu>` |
+
+## Style Rules
+
+- **Theme tokens**: Use CSS variables from `globals.css` (`--primary`, `--secondary`, `--muted`, etc.)
+- **Layout**: Use Tailwind CSS utilities (`grid grid-cols-12`, `flex items-center justify-between gap-3`)
+- **Spacing**: Tailwind utilities (`p-3`, `m-2`, `space-y-4`)
+- **Colors**: Always use theme variables (`bg-primary`, `text-muted-foreground`), never hardcoded hex
+- **Theme customization**: Modify CSS variables in `globals.css` or `tailwind.config`
+- **Component variants**: Use the `cn()` utility for conditional classes
+
+## Icon Reference
+
+Lucide React: `import { IconName } from "lucide-react"`
+
+Common: `Check`, `X`, `Search`, `Plus`, `Trash2`, `Pencil`, `User`, `Settings`, `Download`, `Upload`, `RefreshCw`, `Filter`, `ArrowUpDown`, `Eye`, `EyeOff`
+
+Full list: https://lucide.dev/icons

package/template/.forge/templates/framework-absorption/generic.md

@@ -0,0 +1,52 @@
+# Generic Framework Absorption Reference
+
+This file is used when the `forge` skill detects an unknown or custom meta-prompting framework during brownfield init.
+
+## Detection Signals
+
+Any of these suggest a meta-prompting framework is present:
+
+```
+.claude/agents/ or agents/         # Agent definitions
+.claude/skills/ or skills/         # Skill definitions
+CLAUDE.md with routing tables      # Framework entry point
+workflows/ or commands/            # Workflow definitions
+templates/ with spec/plan files    # Structured templates
+Any *.md files describing agent roles, workflows, or governance rules
+```
+
+## Discovery Process
+
+Since the framework is unknown, use the `researching` skill to understand it:
+
+1. **Identify the entry point** — Look for CLAUDE.md, README.md, or the largest markdown file
+2. **Map the structure** — List all directories and key files
+3. **Classify content** — For each file, determine if it contains:
+   - Project information (→ `.forge/project.yml`)
+   - Requirements or specifications (→ `.forge/requirements.yml`)
+   - Plans or roadmaps (→ `.forge/roadmap.yml`)
+   - State or progress tracking (→ `.forge/state/index.yml` + `.forge/state/milestone-{id}.yml`)
+   - Decisions or constraints (→ `.forge/context.md`)
+   - Governance rules (→ `.forge/constitution.md`)
+   - Design/UI rules (→ `.forge/design-system.md`)
+   - Agent definitions (→ `.claude/agents/`)
+   - Workflow/skill logic (→ `.claude/skills/`)
+4. **Present findings** — Show the mapping to the user before converting
+
+## Conversion Principles
+
+- **Preserve all project knowledge** — Nothing gets discarded. If it doesn't fit a Forge file, add it to `.forge/context.md` under "Carried Forward".
+- **YAML for machine state** — If the original used prose for state tracking, convert to YAML.
+- **Markdown for human content** — Keep human-facing docs as markdown.
+- **Ask when uncertain** — If a file's purpose is unclear, ask the user rather than guessing.
+
+## Absorption Checklist
+
+- [ ] Framework structure mapped and understood
+- [ ] All content files classified by type
+- [ ] Project info extracted to `.forge/project.yml`
+- [ ] Requirements extracted to `.forge/requirements.yml`
+- [ ] Governance rules mapped to `.forge/constitution.md`
+- [ ] Remaining knowledge captured in `.forge/context.md`
+- [ ] Original framework files archived in `.forge/archive/{name}/`
+- [ ] User confirmed conversion results