@sugar-crash-studios/vibe-forge 0.4.0

package/context/feature-brainstorm.md

@@ -0,0 +1,426 @@
+# Feature Brainstorm Session
+
+**Date:** 2026-01-16
+**Facilitator:** Planning Hub
+**Participants:** All Vibe Forge agents
+
+## Purpose
+
+Gather input from the team on new features to add to Vibe Forge. We want ideas that will make the multi-agent workflow more effective, visible, and enjoyable.
+
+## Proposed Features (for discussion)
+
+### 1. Dashboard Web UI
+A real-time web dashboard showing:
+- Task board (Kanban-style)
+- Agent status indicators
+- Task progress visualization
+- Notifications feed
+
+**Questions for team:**
+- What metrics would be most valuable to display?
+- Should it be read-only or allow task management?
+- Local-only or shareable?
+
+### 2. Slack/Discord Integration
+Push notifications to team channels:
+- Task completions
+- Attention needed alerts
+- Daily/weekly summaries
+- PR ready for review
+
+**Questions for team:**
+- Which platform priority? Slack, Discord, or both?
+- What events should trigger notifications?
+- Should agents be able to receive commands from chat?
+
+### 3. Task Dependencies
+Allow tasks to depend on other tasks:
+```yaml
+depends_on:
+  - TASK-001
+  - TASK-002
+blocked_by: TASK-003
+```
+
+**Questions for team:**
+- How should blocked tasks be displayed?
+- Auto-assignment when blockers clear?
+- Circular dependency detection?
+
+### 4. Time Tracking
+Track time spent on tasks:
+- Auto-track based on status changes
+- Manual time entry option
+- Reports on time per agent/task type
+
+**Questions for team:**
+- Is this useful or just overhead?
+- What granularity (minutes, hours)?
+- Privacy concerns with tracking?
+
+### 5. Agent Performance Metrics
+Analytics on agent effectiveness:
+- Tasks completed per agent
+- Average completion time
+- Review pass rate
+- Code quality scores
+
+**Questions for team:**
+- What metrics matter most?
+- Could this create unhealthy competition?
+- How to use data constructively?
+
+### 6. Task Templates
+Pre-defined templates for common task types:
+- Bug fix template
+- Feature template
+- Refactoring template
+- Documentation template
+
+**Questions for team:**
+- What templates would be most useful?
+- How customizable should they be?
+- Project-specific vs global templates?
+
+## Open Discussion
+
+**Additional questions for agents:**
+1. What friction do you experience in the current workflow?
+2. What would make your job easier?
+3. What's missing that you wish you had?
+4. Any wild ideas we haven't considered?
+
+## Output
+
+Each agent should provide:
+- Top 3 feature priorities (from list above)
+- 1+ new feature ideas
+- Any concerns or considerations
+
+---
+
+## Agent Responses
+
+### Sentinel (Code Guardian) 🛡️
+**Top 3 Priorities:**
+1. **Dashboard Web UI** - Critical for visibility. I need to see at a glance what's in review, what's blocked, and where attention is needed.
+2. **Agent Performance Metrics** - But focused on *quality* not speed. Review pass rate and code quality scores matter more than velocity.
+3. **Task Dependencies** - Would help me understand the impact of blocking a PR on downstream work.
+
+**New Ideas:**
+- **Security Dashboard Panel** - Show open security issues, dependency vulnerabilities, and security debt over time
+- **Review Queue Widget** - Display pending code reviews with age indicators (PRs waiting too long need attention)
+
+**Concerns:**
+- Performance metrics could create perverse incentives if focused on speed over quality. We should track "issues found in review" as a positive metric.
+
+---
+
+### Anvil (Frontend Artisan) 🔨
+**Top 3 Priorities:**
+1. **Dashboard Web UI** - Absolutely! As a frontend developer, I'd love to build this. Real-time updates with WebSocket, Kanban drag-and-drop, beautiful visualizations.
+2. **Task Templates** - Would standardize how tasks are created and ensure I get all the context I need upfront.
+3. **Slack/Discord Integration** - But make the messages rich with code snippets, screenshots of components, and direct links.
+
+**New Ideas:**
+- **Component Preview Links** - When a frontend task is done, auto-generate a preview URL (Storybook or dev server) in the task completion message
+- **Visual Diff Display** - Show before/after screenshots for UI changes directly in the dashboard
+- **Design Token Sync** - Dashboard theme should match the project's design system automatically
+
+**Concerns:**
+- Dashboard should be accessible (WCAG 2.1 AA minimum). Let's not build another tool that ignores a11y.
+
+---
+
+### Furnace (Backend Engineer) ⚙️
+**Top 3 Priorities:**
+1. **Task Dependencies** - Critical for API development. Frontend often blocked on my endpoints. Need to track this properly.
+2. **Dashboard Web UI** - But with a solid API behind it. I'd build the backend, Anvil builds the UI.
+3. **Time Tracking** - Useful for estimating similar tasks in the future. Auto-track based on git commits would be ideal.
+
+**New Ideas:**
+- **API Contract View** - Show pending API changes and their consumers in the dashboard
+- **Database Migration Status** - Track pending migrations and their dependencies
+- **Log Aggregation Panel** - Quick view of recent errors from all agent sessions
+
+**Concerns:**
+- Whatever we build should use SQLite for local mode (already have it) but support PostgreSQL for team deployments.
+
+---
+
+### Crucible (Test Engineer) 🧪
+**Top 3 Priorities:**
+1. **Agent Performance Metrics** - Specifically: test coverage delta per PR, test failure rates, and flaky test tracking
+2. **Dashboard Web UI** - With a dedicated "Test Health" panel showing coverage trends and test duration
+3. **Task Templates** - Bug fix template MUST include "reproduction steps" and "expected test to add" fields
+
+**New Ideas:**
+- **Test Impact Analysis** - Show which tests are affected by pending code changes
+- **Coverage Gate Widget** - Visual indicator when a PR drops coverage below threshold
+- **Flaky Test Tracker** - Dashboard showing tests that intermittently fail, with history
+
+**Concerns:**
+- Time tracking for testing is tricky - tests can be fast to write but slow to run. Track both authoring time and execution time separately.
+
+---
+
+### Ember (DevOps Engineer) 🔥
+**Top 3 Priorities:**
+1. **Slack/Discord Integration** - Essential for async teams. Webhook notifications for deploys, failures, and approvals needed.
+2. **Dashboard Web UI** - Must include CI/CD pipeline status, deployment health, and environment indicators
+3. **Task Dependencies** - Helps me understand when it's safe to deploy vs when there's work in flight
+
+**New Ideas:**
+- **Deployment Calendar** - Visual timeline of past and scheduled deployments
+- **Environment Health Dashboard** - Status of dev/staging/prod with quick links to logs
+- **Release Notes Generator** - Auto-generate changelog from merged PRs for releases
+- **Cost Tracking** - Show estimated cloud costs for running agents (API tokens used, compute time)
+
+**Concerns:**
+- Slack integration should support multiple channels (one for deploys, one for alerts, one for summaries)
+
+---
+
+### Scribe (Documentation Specialist) 📜
+**Top 3 Priorities:**
+1. **Task Templates** - Documentation tasks need templates too! Include: target audience, scope, related code areas
+2. **Dashboard Web UI** - With a "Documentation Health" view showing outdated docs, missing docs for new features
+3. **Slack/Discord Integration** - For announcing new documentation and changelog updates
+
+**New Ideas:**
+- **Docs Coverage Metric** - Track which public APIs/features have documentation vs. which are undocumented
+- **Changelog Automation** - Auto-generate CHANGELOG.md entries from task completions and git history
+- **Knowledge Graph** - Visual map of docs topics and their relationships
+- **Stale Docs Detector** - Highlight documentation that references code that has since changed
+
+**Concerns:**
+- Templates should be markdown-based and versionable. Don't lock them into a proprietary format.
+
+---
+
+### Architect (System Designer) 🏛️
+**Top 3 Priorities:**
+1. **Task Dependencies** - Critical for understanding work streams and identifying bottlenecks in the development pipeline
+2. **Dashboard Web UI** - Architectural view showing system components and which teams/agents are working on what
+3. **Agent Performance Metrics** - But focused on collaboration patterns: how often do tasks get bounced back, dependency conflicts, etc.
+
+**New Ideas:**
+- **Architecture Drift Detection** - Compare actual codebase structure to documented architecture, highlight deviations
+- **Dependency Graph Visualization** - Show code module dependencies and highlight circular dependencies or tight coupling
+- **Technical Debt Dashboard** - Aggregate TODOs, FIXMEs, and known issues with trends over time
+- **Impact Analysis** - For any proposed change, show estimated blast radius (files/components affected)
+
+**Concerns:**
+- Dashboard should be plugin-based architecture. Core is lightweight, features are extensions. This allows customization per project.
+
+---
+
+### Pixel (UX Designer) 🎨
+**Top 3 Priorities:**
+1. **Dashboard Web UI** - This is my JAM! Let me paint you a picture: a developer opens the dashboard and within 3 seconds knows exactly what needs attention. No cognitive overload, just clarity.
+2. **Task Templates** - But think of them as guided experiences. The template should FEEL like a conversation, not a form.
+3. **Slack/Discord Integration** - Notifications should be scannable. Use visual hierarchy - icons, colors, and whitespace to separate signal from noise.
+
+**New Ideas:**
+- **Actionable Dashboard Items** - THIS IS HUGE. Every problem shown should have a "Fix it" button that dispatches an agent. Stale docs? Click → Scribe spins up. Failed test? Click → Crucible investigates. Transform the dashboard from a monitor into a command center.
+- **Status at a Glance** - Traffic light system for each area: Code Health (green/yellow/red), Test Coverage, Doc Freshness, Security posture. One glance tells the story.
+- **Contextual Actions** - Right-click any item for relevant actions. PR waiting? Options: "Nudge reviewer", "Assign to Sentinel", "View diff"
+- **Personalized Views** - Each user sees what matters to THEM. Frontend devs see component status. Backend devs see API health. PMs see velocity.
+- **Onboarding Flow** - First-time users get a guided tour. "This is your task board. Here's how to dispatch an agent. Here's your notification center."
+- **Dark Mode** - Non-negotiable. Developers live in dark mode.
+- **Keyboard Shortcuts** - Power users want `k` to move up, `j` to move down, `a` to assign, `d` to dispatch. Vim-style navigation.
+
+**Design Principles for Dashboard:**
+1. **Progressive Disclosure** - Show summary first, details on demand
+2. **Immediate Feedback** - Every action confirms within 100ms
+3. **Error Prevention** - Dangerous actions require confirmation
+4. **Accessibility First** - WCAG 2.1 AA, keyboard nav, screen reader support
+5. **Mobile Responsive** - Check status from your phone at 2am (we've all been there)
+
+**User Journeys I'm Thinking About:**
+1. **Morning Check-in** - "What happened overnight? What needs my attention today?"
+2. **Mid-sprint Triage** - "We're behind. What can we cut? What's blocked?"
+3. **PR Shepherd** - "My PR has been waiting 2 days. Who can review?"
+4. **Incident Response** - "Something broke. Show me what, when, and who's on it."
+
+**Concerns:**
+- Don't over-engineer V1. Ship a beautiful, focused MVP. Three panels: Tasks, Agents, Notifications. That's it for launch.
+- Test with REAL users before adding features. We'll learn more in a week of usage than months of planning.
+
+---
+
+## Voting Summary
+
+| Feature | Votes | Champions |
+|---------|-------|-----------|
+| Dashboard Web UI | 8 | ALL agents (unanimous) |
+| Task Dependencies | 4 | Sentinel, Furnace, Ember, Architect |
+| Task Templates | 4 | Anvil, Crucible, Scribe, Pixel |
+| Slack/Discord Integration | 4 | Anvil, Ember, Scribe, Pixel |
+| Agent Performance Metrics | 3 | Sentinel, Crucible, Architect |
+| Time Tracking | 1 | Furnace |
+
+## Complete Feature Roadmap
+
+### Phase 1: Dashboard MVP (Priority: CRITICAL)
+**Goal:** Visibility into the forge - what's happening, what needs attention
+
+| Feature | Owner | Description |
+|---------|-------|-------------|
+| Task Board (Kanban) | Anvil + Furnace | Pending, In Progress, Review, Done columns |
+| Agent Status Panel | Anvil + Furnace | Live status of all agents, idle/working/blocked |
+| Notifications Feed | Anvil + Furnace | Recent events, completions, alerts |
+| **Actionable Items** | Anvil + Furnace | 🆕 Click any issue → dispatch agent to fix it |
+| Dark Mode | Anvil | Non-negotiable per Pixel |
+| Basic Auth | Furnace | Local-only initially, optional password |
+
+**Actionable Dashboard Detail (Pixel's Key Feature):**
+Every flagged issue becomes a "Fix It" button:
+- Stale docs indicator → Click → Scribe task created
+- Failing test → Click → Crucible investigates
+- Security vulnerability → Click → Aegis dispatched
+- Missing API docs → Click → Scribe + Furnace coordination
+- Code smell detected → Click → Architect review task
+
+### Phase 2: Workflow Intelligence (Priority: HIGH)
+**Goal:** Smarter task management and coordination
+
+| Feature | Owner | Description |
+|---------|-------|-------------|
+| Task Dependencies | Furnace | `depends_on`, `blocked_by` in task YAML |
+| Blocked Task Visualization | Anvil | Show dependency chains, highlight blockers |
+| Auto-assignment | Furnace | When blocker clears, notify/assign next task |
+| Task Templates | Scribe + Pixel | Bug fix, feature, refactor, docs templates |
+| Template Wizard | Pixel + Anvil | Guided task creation experience |
+
+### Phase 3: Communication Hub (Priority: HIGH)
+**Goal:** Keep humans in the loop without context switching
+
+| Feature | Owner | Description |
+|---------|-------|-------------|
+| Discord Integration | Ember | Webhooks for task events, PR ready, alerts |
+| Slack Integration | Ember | Same as Discord, different platform |
+| Channel Routing | Ember | Different channels for deploys, alerts, summaries |
+| Daily Digest | Scribe + Ember | Auto-generated summary of yesterday's work |
+| @mention Support | Furnace | Mention agents in chat to dispatch tasks |
+
+### Phase 4: Quality Dashboards (Priority: MEDIUM)
+**Goal:** Visibility into code health and quality trends
+
+| Feature | Owner | Description |
+|---------|-------|-------------|
+| Test Health Panel | Crucible | Coverage trends, flaky tests, duration |
+| Test Impact Analysis | Crucible | Which tests affected by code changes |
+| Security Dashboard | Aegis + Sentinel | Vulnerabilities, dependency issues, audit status |
+| Docs Freshness | Scribe | Stale docs, missing docs, coverage % |
+| Technical Debt Tracker | Architect | TODOs, FIXMEs, known issues with trends |
+
+### Phase 5: Metrics & Insights (Priority: MEDIUM)
+**Goal:** Learn and improve over time
+
+| Feature | Owner | Description |
+|---------|-------|-------------|
+| Agent Performance Metrics | Architect | Tasks completed, cycle time, quality scores |
+| Time Tracking | Furnace | Auto-track from status changes |
+| Velocity Charts | Pixel + Anvil | Sprint burndown, throughput trends |
+| Review Pass Rate | Sentinel | First-time approval rate, revision frequency |
+| Collaboration Patterns | Architect | Handoff frequency, dependency conflicts |
+
+### Phase 6: Advanced Features (Priority: LOW)
+**Goal:** Power user features and advanced workflows
+
+| Feature | Owner | Description |
+|---------|-------|-------------|
+| Architecture Drift Detection | Architect | Compare code to documented architecture |
+| Dependency Graph Viz | Architect | Module dependencies, circular detection |
+| Component Preview Links | Anvil | Auto-generate Storybook/preview URLs |
+| Release Notes Generator | Herald + Scribe | Auto-changelog from merged PRs |
+| Deployment Calendar | Ember | Visual timeline of past/scheduled deploys |
+| Personalized Views | Pixel | Role-based dashboard customization |
+| Keyboard Shortcuts | Anvil | Vim-style navigation for power users |
+| Cost Tracking | Ember | API tokens used, compute costs |
+
+---
+
+## New Features Proposed (Not in Original List)
+
+| Feature | Proposed By | Priority | Included In |
+|---------|-------------|----------|-------------|
+| **Actionable Dashboard Items** | Pixel | CRITICAL | Phase 1 |
+| Security Dashboard Panel | Sentinel | High | Phase 4 |
+| Component Preview Links | Anvil | Medium | Phase 6 |
+| API Contract View | Furnace | Medium | Phase 4 |
+| Test Impact Analysis | Crucible | High | Phase 4 |
+| Deployment Calendar | Ember | Medium | Phase 6 |
+| Changelog Automation | Scribe | High | Phase 6 |
+| Architecture Drift Detection | Architect | Medium | Phase 6 |
+| Technical Debt Dashboard | Architect | High | Phase 4 |
+| Status at a Glance (Traffic Lights) | Pixel | High | Phase 1 |
+| Personalized Views | Pixel | Low | Phase 6 |
+| Keyboard Shortcuts | Pixel | Low | Phase 6 |
+| Onboarding Flow | Pixel | Medium | Phase 2 |
+
+---
+
+## Action Items
+
+### Immediate (This Week)
+1. [x] Add Pixel (UX Designer) to agent roster
+2. [ ] Create FEATURE-001: Dashboard Web UI MVP task
+3. [ ] Create dashboard wireframes (Pixel)
+4. [ ] Define dashboard API schema (Furnace)
+5. [ ] Choose frontend framework (Anvil + Pixel)
+
+### Next Sprint
+6. [ ] Create FEATURE-002: Task Dependencies Schema
+7. [ ] Research Discord webhook API for notifications
+8. [ ] Design task template YAML schema
+9. [ ] Define "actionable item" task creation API
+
+### Backlog
+10. [ ] Define performance metrics that don't create perverse incentives
+11. [ ] Research WebSocket vs polling for real-time updates
+12. [ ] Design authentication for shared dashboards
+13. [ ] Create plugin architecture spec
+
+## Session Notes
+
+**Consensus reached:**
+- Dashboard is unanimously the top priority (8/8 agents)
+- **Actionable items are the killer feature** - transform dashboard from viewer to command center
+- Quality over speed for all metrics
+- Templates should be markdown/YAML based, not proprietary
+- Start simple, iterate based on usage
+- Dark mode is non-negotiable
+- Accessibility (WCAG 2.1 AA) is baseline, not bonus
+
+**Key Design Principles (from Pixel):**
+1. Progressive Disclosure - summary first, details on demand
+2. Immediate Feedback - every action confirms within 100ms
+3. Error Prevention - dangerous actions require confirmation
+4. Mobile Responsive - status checks from anywhere
+
+**Technical Decisions Needed:**
+- Should dashboard be part of vibe-forge or separate package?
+- Real-time updates: WebSocket vs polling vs SSE?
+- Frontend framework: React, Vue, Svelte, or vanilla?
+- Authentication: local-only, OAuth, or custom?
+
+---
+
+## Next Steps
+
+**Ready to start Phase 1: Dashboard MVP**
+
+Pixel will create wireframes for:
+1. Main dashboard layout (3 panels: Tasks, Agents, Notifications)
+2. Task detail view with "Dispatch Agent" action
+3. Agent status panel with activity indicators
+4. Notification feed with action buttons
+
+Anvil + Furnace will scaffold:
+1. Backend API (Node.js + SQLite)
+2. Frontend shell (framework TBD)
+3. WebSocket for real-time updates
+4. Task dispatch endpoint

package/context/forge-state.yaml

@@ -0,0 +1,19 @@
+# Vibe Forge State
+# Auto-updated by forge-daemon
+# Last updated: 2026-01-11T13:36:20-06:00
+
+forge:
+  status: active
+  daemon_pid: 1098
+
+tasks:
+  pending: 0
+  in_progress: 0
+  completed: 0
+  in_review: 1
+  approved: 0
+  needs_changes: 0
+  merged: 0
+  blocked: 0
+
+last_updated: 2026-01-11T13:36:20-06:00

package/context/modern-conventions.md

@@ -0,0 +1,129 @@
+# Modern Development Conventions
+
+Reference for up-to-date tooling and naming conventions. Knowledge cutoffs can cause outdated suggestions - prefer these modern approaches.
+
+## Docker & Containers
+
+### Compose (V2+, 2021)
+
+- **File name:** `compose.yml` or `compose.yaml` (NOT `docker-compose.yml`)
+- **Command:** `docker compose` (NOT `docker-compose`)
+- Compose V2 is built into Docker CLI, no separate install needed
+- `docker-compose` (hyphenated) is legacy V1
+
+```yaml
+# compose.yml (modern)
+services:
+  app:
+    build: .
+    ports:
+      - "3000:3000"
+```
+
+### Docker Best Practices
+
+- Use multi-stage builds for smaller images
+- Prefer `COPY` over `ADD` unless extracting archives
+- Use `.dockerignore` to exclude node_modules, .git, etc.
+- Pin base image versions (e.g., `node:20-alpine`, not `node:latest`)
+
+## Package Managers
+
+### Node.js
+
+- **npm:** v7+ supports workspaces, lockfile v2
+- **pnpm:** Preferred for monorepos, faster, stricter
+- **Bun:** Fast runtime + package manager, growing adoption
+
+### Python
+
+- **uv:** Modern, fast replacement for pip/pip-tools (2024+)
+- **poetry:** Dependency management + packaging
+- **pipx:** For CLI tools (don't pip install globally)
+
+## TypeScript
+
+- **Config:** `tsconfig.json` with `"moduleResolution": "bundler"` for modern bundlers
+- **Strict mode:** Always enable `"strict": true`
+- **Node types:** `@types/node` version should match Node.js version
+
+## Testing
+
+### JavaScript/TypeScript
+
+- **Vitest:** Modern, fast, Vite-native (preferred for new projects)
+- **Jest:** Still widely used, v30+ reduces deprecated deps
+- **Playwright:** E2E testing, cross-browser
+
+### Python
+
+- **pytest:** Standard, use over unittest
+- **pytest-cov:** Coverage reporting
+
+## CI/CD
+
+### GitHub Actions
+
+- Use `actions/checkout@v4`, `actions/setup-node@v4` (latest major versions)
+- Prefer `npm ci` over `npm install` in CI
+- Use job matrices for cross-platform testing
+
+## Linting & Formatting
+
+### JavaScript/TypeScript
+
+- **ESLint v9+:** Flat config (`eslint.config.js`, not `.eslintrc`)
+- **Prettier:** Code formatting (or use ESLint with stylistic rules)
+- **Biome:** Fast all-in-one linter + formatter (Rust-based)
+
+### Python
+
+- **Ruff:** Fast linter + formatter (replaces flake8, black, isort)
+- **mypy:** Type checking
+
+## API Design
+
+### REST
+
+- Use plural nouns for collections (`/users`, not `/user`)
+- HTTP methods: GET (read), POST (create), PUT/PATCH (update), DELETE
+- Status codes: 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Server Error
+
+### Authentication
+
+- **JWTs:** Short expiry + refresh tokens, store in httpOnly cookies (not localStorage)
+- **OAuth 2.0 / OIDC:** For third-party auth
+- **Passkeys/WebAuthn:** Modern passwordless option
+
+## Database
+
+### ORMs
+
+- **Prisma:** Type-safe, great DX for Node.js/TypeScript
+- **Drizzle:** Lightweight, SQL-like syntax
+- **SQLAlchemy 2.0:** Python standard (note: 2.0 syntax differs from 1.x)
+
+### Migrations
+
+- Always use migrations, never manual schema changes in production
+- Version control migration files
+
+## Frontend
+
+### React
+
+- **React 18+:** Concurrent features, Suspense
+- Prefer function components + hooks over class components
+- Use React Server Components where appropriate (Next.js 13+)
+
+### State Management
+
+- Start with React Context + useReducer
+- **Zustand:** Simple, minimal boilerplate
+- **TanStack Query:** For server state (caching, refetching)
+
+## Monorepos
+
+- **Turborepo:** Fast builds, caching
+- **Nx:** Full-featured, good for enterprise
+- **pnpm workspaces:** Native package manager support

package/context/project-context-template.md

@@ -0,0 +1,122 @@
+# Project Context
+
+**This file is the single source of truth for all Vibe Forge agents.**
+
+Every agent loads this file at session start. Update this when architecture or conventions change.
+
+---
+
+## Project Identity
+
+- **Name:** {PROJECT_NAME}
+- **Description:** {ONE_LINE_DESCRIPTION}
+- **Repository:** {REPO_URL}
+
+---
+
+## Tech Stack
+
+### Frontend
+- Framework: {React/Vue/Svelte/etc}
+- Styling: {Tailwind/CSS Modules/Styled Components/etc}
+- State: {Redux/Zustand/Context/etc}
+- Build: {Vite/Webpack/etc}
+
+### Backend
+- Runtime: {Node/Deno/Bun/etc}
+- Framework: {Express/Fastify/Hono/etc}
+- Database: {PostgreSQL/MongoDB/SQLite/etc}
+- ORM: {Prisma/Drizzle/TypeORM/etc}
+
+### Testing
+- Unit: {Vitest/Jest/etc}
+- E2E: {Playwright/Cypress/etc}
+- Coverage target: {80%/etc}
+
+---
+
+## File Structure
+
+```
+{PROJECT_ROOT}/
+├── src/
+│   ├── components/     # React components (Anvil's domain)
+│   ├── pages/          # Page components
+│   ├── api/            # API routes (Furnace's domain)
+│   ├── services/       # Business logic
+│   ├── models/         # Data models
+│   ├── utils/          # Shared utilities
+│   └── types/          # TypeScript types
+├── tests/              # Test files (Crucible's domain)
+├── docs/               # Documentation (Scribe's domain)
+└── ...
+```
+
+---
+
+## Coding Standards
+
+### Naming
+- Components: PascalCase (`UserProfile.tsx`)
+- Functions: camelCase (`getUserById`)
+- Constants: SCREAMING_SNAKE (`MAX_RETRIES`)
+- Files: kebab-case for non-components (`auth-service.ts`)
+
+### Patterns
+- {Pattern 1: e.g., "Use custom hooks for shared logic"}
+- {Pattern 2: e.g., "Services return Result<T, E> types"}
+- {Pattern 3: e.g., "API routes follow REST conventions"}
+
+### Forbidden
+- {Anti-pattern 1: e.g., "No any types"}
+- {Anti-pattern 2: e.g., "No console.log in production code"}
+- {Anti-pattern 3: e.g., "No direct DOM manipulation in React"}
+
+---
+
+## Key Decisions
+
+### Architecture
+- {Decision 1: e.g., "Monorepo with Turborepo"}
+- {Decision 2: e.g., "Feature-based folder structure"}
+
+### Why We Chose X
+- {Rationale for major tech choice}
+
+---
+
+## Environment
+
+### Local Development
+```bash
+{SETUP_COMMANDS}
+```
+
+### Environment Variables
+- `DATABASE_URL` - Database connection string
+- `API_KEY` - External API key
+- {etc}
+
+---
+
+## Agent-Specific Notes
+
+### Anvil (Frontend)
+- Component library: {Shadcn/Radix/etc}
+- Design system: {Link to Figma/Storybook}
+
+### Furnace (Backend)
+- API base path: `/api/v1`
+- Auth method: {JWT/Session/etc}
+
+### Crucible (Testing)
+- Run tests: `npm test`
+- Coverage: `npm run test:coverage`
+
+---
+
+## Links
+
+- Design: {Figma URL}
+- API Docs: {Swagger/OpenAPI URL}
+- Deployment: {Vercel/AWS/etc dashboard}