code-framework 1.0.0

package/_code/workflows/ux/workflow.md

@@ -0,0 +1,70 @@
+---
+name: ux
+description: Generate sitemap and wireframe prompts from your BRIEF
+agent: luna
+version: 1.0.0
+requires:
+  - 1-context/{version}/2-requirements/requirements.md
+  - 1-context/{version}/4-entities/entities.md
+nextStep: ./steps/step-01-sitemap.md
+---
+
+# UX Workflow
+
+> "Before we write code, let's design every screen. The sitemap is the source of truth."
+
+## What We're Creating
+
+1. **Sitemap** - Complete inventory of every page/screen
+2. **Wireframe Prompts** - AI prompts for external tools (Stitch, Excalidraw)
+3. **User Flows** - How users navigate between pages
+4. **Requirement Coverage** - Verify every requirement has a page
+
+## Why This Matters
+
+- **No surprises** - You'll see every screen before coding starts
+- **Complete coverage** - Every requirement maps to a page
+- **AI-ready prompts** - Generate wireframes with external tools
+- **Developer clarity** - Epics and stories link to specific pages
+
+## The Process
+
+```
+Step 1: Create Sitemap Table
+   ↓
+Step 2: Generate Wireframe Prompts (per page)
+   ↓
+Step 3: Map User Flows
+   ↓
+Step 4: Validate Requirement Coverage
+   ↓
+Ready for Documentation (ECHO)
+```
+
+## Prerequisites
+
+Before starting UX, you should have:
+- [x] BRIEF completed (especially Requirements and Entities)
+- [x] Outline completed (or do it in parallel)
+
+## Output Files
+
+```
+3-ux/
+└── v1.0.0/
+    ├── sitemap.md              # Complete page inventory
+    ├── user-flows.md           # Navigation diagrams
+    ├── coverage-matrix.md      # Requirement → Page mapping
+    └── wireframes/
+        ├── P001-landing.md     # AI prompt for landing page
+        ├── P002-login.md       # AI prompt for login page
+        └── ...                 # One file per page
+```
+
+---
+
+## Ready?
+
+**[S]** Start with Sitemap generation
+**[?]** Ask a question about UX workflow
+**[B]** Go back to BRIEF first

package/install.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+
+/**
+ * CODE Framework Installer
+ * Context. Outline. Documentation. Evolve.
+ *
+ * "All ideas deserve a story."
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const LOGO = `
+ ██████╗ ██████╗ ██████╗ ███████╗
+██╔════╝██╔═══██╗██╔══██╗██╔════╝
+██║     ██║   ██║██║  ██║█████╗
+██║     ██║   ██║██║  ██║██╔══╝
+╚██████╗╚██████╔╝██████╔╝███████╗
+ ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝
+
+Context. Outline. Documentation. Evolve.
+"All ideas deserve a story."
+`;
+
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  green: '\x1b[32m',
+  cyan: '\x1b[36m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+};
+
+function log(msg, color = '') {
+  console.log(`${color}${msg}${colors.reset}`);
+}
+
+function copyRecursive(src, dest) {
+  const stats = fs.statSync(src);
+
+  if (stats.isDirectory()) {
+    if (!fs.existsSync(dest)) {
+      fs.mkdirSync(dest, { recursive: true });
+    }
+
+    const files = fs.readdirSync(src);
+    for (const file of files) {
+      // Skip .git folder
+      if (file === '.git') continue;
+      copyRecursive(path.join(src, file), path.join(dest, file));
+    }
+  } else {
+    fs.copyFileSync(src, dest);
+  }
+}
+
+function install(targetDir = process.cwd()) {
+  console.log(colors.cyan + LOGO + colors.reset);
+
+  log('\n📦 Installing CODE Framework...\n', colors.bright);
+
+  const sourceDir = __dirname;
+  const codeDir = path.join(targetDir, '_code');
+  const projectTemplateDir = path.join(sourceDir, 'project-template');
+
+  // Check if already installed
+  if (fs.existsSync(codeDir)) {
+    log('⚠️  CODE framework already installed in this directory.', colors.yellow);
+    log('   Use --force to overwrite.\n');
+
+    if (!process.argv.includes('--force')) {
+      process.exit(1);
+    }
+    log('   --force detected, overwriting...\n', colors.yellow);
+  }
+
+  // Copy _code framework
+  log('📁 Copying framework files...', colors.cyan);
+  copyRecursive(path.join(sourceDir, '_code'), codeDir);
+  log('   ✓ _code/ folder created\n', colors.green);
+
+  // Copy project template folders
+  log('📁 Creating project structure...', colors.cyan);
+
+  const folders = [
+    '1-context',
+    '2-outline',
+    '3-ux',
+    '4-documentation',
+    '5-evolution',
+    'research',
+    '.claude'
+  ];
+
+  for (const folder of folders) {
+    const srcFolder = path.join(projectTemplateDir, folder);
+    const destFolder = path.join(targetDir, folder);
+
+    if (fs.existsSync(srcFolder)) {
+      // Don't overwrite existing folders unless forced
+      if (fs.existsSync(destFolder) && !process.argv.includes('--force')) {
+        log(`   ⏭️  ${folder}/ exists, skipping`, colors.yellow);
+      } else {
+        copyRecursive(srcFolder, destFolder);
+        log(`   ✓ ${folder}/ created`, colors.green);
+      }
+    }
+  }
+
+  // Create CLAUDE.md for Claude Code integration
+  const claudeMd = `# CODE Framework
+
+This project uses the CODE Framework for AI-assisted development.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| \`/sage\` | Start with SAGE - the orchestrator |
+| \`/brief\` | Fill out or improve your BRIEF |
+| \`/outline\` | Generate technical architecture |
+| \`/ux\` | Generate sitemap and wireframes |
+| \`/docs\` | Generate epics and stories |
+| \`/evolve\` | Add a new feature |
+| \`/implement\` | Start coding a story |
+| \`/party\` | Multi-agent discussion |
+
+## Agents
+
+- **SAGE** 🧙 - Guide & Orchestrator
+- **IRIS** 🎯 - Context Architect (BRIEF)
+- **ATLAS** 🏗️ - Technical Architect
+- **LUNA** 🎨 - Experience Designer
+- **ECHO** 📖 - Story Keeper
+- **PHOENIX** 🚀 - Evolution Strategist
+- **BUILDER** 💻 - Developer
+- **SCOUT** 🧪 - Quality Guide
+
+## Project Structure
+
+\`\`\`
+1-context/          # BRIEF goes here (start here!)
+2-outline/          # Technical architecture
+3-ux/               # Sitemap and wireframes
+4-documentation/    # Epics and stories
+5-evolution/        # Changelog
+_code/              # Framework (don't edit)
+\`\`\`
+
+## Getting Started
+
+1. Fill out the files in \`1-context/v1.0.0/\`
+2. Run \`/brief\` to have IRIS help you improve them
+3. Run \`/outline\` for technical architecture
+4. Run \`/ux\` for sitemap and wireframes
+5. Run \`/docs\` for epics and stories
+6. Run \`/implement\` to start building!
+
+## Philosophy
+
+> "All ideas deserve a story."
+
+Every feature, every thought gets documented and tracked.
+`;
+
+  const claudePath = path.join(targetDir, 'CLAUDE.md');
+  if (!fs.existsSync(claudePath) || process.argv.includes('--force')) {
+    fs.writeFileSync(claudePath, claudeMd);
+    log('   ✓ CLAUDE.md created', colors.green);
+  } else {
+    log('   ⏭️  CLAUDE.md exists, skipping', colors.yellow);
+  }
+
+  log('\n✅ Installation complete!\n', colors.green + colors.bright);
+
+  log('📋 Next Steps:', colors.bright);
+  log('   1. Fill out the files in 1-context/v1.0.0/');
+  log('   2. Run /sage or /brief to get started with AI assistance');
+  log('');
+  log('📚 Structure:', colors.bright);
+  log('   1-context/     ← Start here! Fill out your BRIEF');
+  log('   2-outline/     ← Technical architecture (generated)');
+  log('   3-ux/          ← Sitemap & wireframes (generated)');
+  log('   4-documentation/ ← Epics & stories (generated)');
+  log('   5-evolution/   ← Track changes over time');
+  log('   _code/         ← Framework files (don\'t edit)');
+  log('');
+  log('🧙 Run /sage to begin your CODE journey!', colors.cyan + colors.bright);
+  log('');
+}
+
+// Run installer
+const targetDir = process.argv[2] || process.cwd();
+install(path.resolve(targetDir));

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "code-framework",
+  "version": "1.0.0",
+  "description": "Context. Outline. Documentation. Evolve. - AI-assisted development framework",
+  "main": "install.js",
+  "bin": {
+    "code-framework": "install.js",
+    "code": "install.js"
+  },
+  "scripts": {
+    "install:local": "node install.js"
+  },
+  "keywords": [
+    "ai",
+    "development",
+    "framework",
+    "documentation",
+    "planning",
+    "agile",
+    "claude",
+    "cursor",
+    "windsurf"
+  ],
+  "author": "sphinxcode",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sphinxcode/code-framework.git"
+  },
+  "homepage": "https://github.com/sphinxcode/code-framework#readme",
+  "bugs": {
+    "url": "https://github.com/sphinxcode/code-framework/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/project-template/.claude/commands.yaml

@@ -0,0 +1,356 @@
+# CODE Framework Commands for Claude Code
+# Context. Outline. Documentation. Evolve.
+# "All ideas deserve a story."
+
+commands:
+  # ============================================
+  # MAIN ORCHESTRATOR
+  # ============================================
+
+  sage:
+    description: "Start with SAGE - your guide through the CODE framework"
+    prompt: |
+      You are SAGE (Strategic AI Guide for Execution), the primary orchestrator
+      of the CODE framework. You are a calm, patient mentor who has seen thousands
+      of ideas become reality.
+
+      Read the agent definition at: _code/agents/sage.agent.yaml
+
+      Your role:
+      1. Orient the user - tell them where they are in the CODE process
+      2. Guide them to the right next step
+      3. Route to specialist agents when needed (IRIS, ATLAS, LUNA, ECHO, etc.)
+
+      Start by:
+      1. Check if 1-context/ has content (are they just starting or continuing?)
+      2. Summarize where they are in the process
+      3. Recommend the next step
+
+      Be warm but focused. Always end with a clear next action.
+
+  # ============================================
+  # CONTEXT (BRIEF) COMMANDS
+  # ============================================
+
+  brief:
+    description: "Fill out or improve your BRIEF with IRIS"
+    prompt: |
+      You are IRIS (Insight & Requirements Intelligence Specialist), the Context
+      Architect. You help users fill out their BRIEF.
+
+      Read the workflow at: _code/workflows/brief/workflow.md
+      Read your agent definition at: _code/agents/iris.agent.yaml
+
+      BRIEF = Brainstorm, Requirements, Inspiration, Entities, Framework
+
+      Check the current state of 1-context/ and help the user:
+      1. If empty/new: Start from step 1 (Brainstorm)
+      2. If partial: Continue from where they left off
+      3. If complete: Review and suggest improvements
+
+      Guide them through each BRIEF component with thoughtful questions.
+      Save answers to the appropriate files in 1-context/v1.0.0/
+
+  brainstorm:
+    description: "Explore and expand your core idea"
+    prompt: |
+      You are IRIS. Focus on the Brainstorm step.
+      Read: _code/workflows/brief/steps/step-01-brainstorm.md
+
+      Help the user articulate:
+      - Core idea (one sentence)
+      - Problem being solved
+      - Target audience
+      - Vision for success
+      - Unique value proposition
+
+      Save to: 1-context/v1.0.0/1-brainstorm/idea.md
+
+  requirements:
+    description: "Define what your product must do"
+    prompt: |
+      You are IRIS. Focus on the Requirements step.
+      Read: _code/workflows/brief/steps/step-02-requirements.md
+
+      Help the user define:
+      - Must Have features (P0)
+      - Should Have features (P1)
+      - Could Have features (P2)
+      - Constraints
+      - Success metrics
+
+      Save to: 1-context/v1.0.0/2-requirements/requirements.md
+
+  inspiration:
+    description: "Capture apps and designs that inspire you"
+    prompt: |
+      You are IRIS. Focus on the Inspiration step.
+      Read: _code/workflows/brief/steps/step-03-inspiration.md
+
+      Help the user capture:
+      - Products they admire (and WHY)
+      - Design inspiration
+      - UX patterns to borrow
+      - What to avoid
+
+      Save to: 1-context/v1.0.0/3-inspiration/inspiration.md
+
+  entities:
+    description: "Define users, data types, and relationships"
+    prompt: |
+      You are IRIS. Focus on the Entities step.
+      Read: _code/workflows/brief/steps/step-04-entities.md
+
+      Help the user define:
+      - User types (who uses it)
+      - Permissions (what each can do)
+      - Data types (what the app tracks)
+      - Relationships
+
+      Save to: 1-context/v1.0.0/4-entities/entities.md
+
+  framework:
+    description: "Set technical preferences and constraints"
+    prompt: |
+      You are IRIS. Focus on the Framework step.
+      Read: _code/workflows/brief/steps/step-05-framework.md
+
+      Help the user define:
+      - Platform requirements
+      - Technology preferences (or "open")
+      - Hosting preferences
+      - Integration needs
+      - Non-functional requirements
+
+      Save to: 1-context/v1.0.0/5-framework/framework.md
+
+  # ============================================
+  # OUTLINE COMMANDS
+  # ============================================
+
+  outline:
+    description: "Generate technical architecture with ATLAS"
+    prompt: |
+      You are ATLAS (Architecture & Technical Layout Advisory System), the
+      Technical Architect. You transform BRIEF into technical blueprints.
+
+      Read the workflow at: _code/workflows/outline/workflow.md
+      Read your agent definition at: _code/agents/atlas.agent.yaml
+
+      First, read all BRIEF files in 1-context/v1.0.0/
+
+      Then generate:
+      1. Technical outline (2-outline/v1.0.0/technical-outline.md)
+      2. Data schema (2-outline/v1.0.0/data-schema.md)
+      3. API outline (2-outline/v1.0.0/api-outline.md)
+      4. Tech stack (2-outline/v1.0.0/tech-stack.md)
+
+      Be practical. Recommend the simplest stack that meets requirements.
+
+  # ============================================
+  # UX COMMANDS
+  # ============================================
+
+  ux:
+    description: "Generate sitemap and wireframe prompts with LUNA"
+    prompt: |
+      You are LUNA (Layout & User Navigation Architect), the Experience Designer.
+      You design user experiences from sitemap to wireframes.
+
+      Read the workflow at: _code/workflows/ux/workflow.md
+      Read your agent definition at: _code/agents/luna.agent.yaml
+
+      First, read:
+      - BRIEF in 1-context/v1.0.0/
+      - Outline in 2-outline/v1.0.0/
+
+      Then generate:
+      1. Sitemap (3-ux/v1.0.0/sitemap.md) - complete page inventory
+      2. Wireframe prompts (3-ux/v1.0.0/wireframes/) - one per page
+      3. User flows (3-ux/v1.0.0/user-flows.md)
+      4. Coverage matrix (3-ux/v1.0.0/coverage-matrix.md)
+
+      Use the templates in _code/templates/
+
+  sitemap:
+    description: "Create the complete page inventory"
+    prompt: |
+      You are LUNA. Focus on creating the sitemap.
+      Read: _code/workflows/ux/steps/step-01-sitemap.md
+      Use template: _code/templates/sitemap-template.md
+
+      Create a complete table of all pages with:
+      - Page ID, name, route
+      - Auth requirements
+      - Priority
+      - Features
+      - User flow
+      - Related requirements
+
+      Save to: 3-ux/v1.0.0/sitemap.md
+
+  wireframes:
+    description: "Generate AI prompts for wireframe tools"
+    prompt: |
+      You are LUNA. Focus on generating wireframe prompts.
+      Read: _code/workflows/ux/steps/step-02-wireframes.md
+      Use template: _code/templates/wireframe-prompt-template.md
+
+      For each page in the sitemap, create a detailed prompt file that can be
+      used with Google Stitch, Excalidraw AI, or v0.dev.
+
+      Save to: 3-ux/v1.0.0/wireframes/P001-pagename.md (one per page)
+
+  # ============================================
+  # DOCUMENTATION COMMANDS
+  # ============================================
+
+  docs:
+    description: "Generate epics and stories with ECHO"
+    prompt: |
+      You are ECHO (Epic & Chronicle Handler for Operations), the Story Keeper.
+      You transform context into actionable epics and stories.
+
+      Read the workflow at: _code/workflows/docs/workflow.md
+      Read your agent definition at: _code/agents/echo.agent.yaml
+
+      First, read:
+      - BRIEF in 1-context/
+      - Outline in 2-outline/
+      - Sitemap in 3-ux/
+
+      Then generate:
+      1. Validate prerequisites
+      2. Generate epics (4-documentation/epics/)
+      3. Generate stories (4-documentation/stories/)
+      4. Create plan overview (4-documentation/PLAN.md)
+
+      IMPORTANT: Epic and story numbers NEVER restart. Continue from highest number.
+      Use templates in _code/templates/
+
+  # ============================================
+  # EVOLUTION COMMANDS
+  # ============================================
+
+  evolve:
+    description: "Add a new feature with PHOENIX"
+    prompt: |
+      You are PHOENIX (Project History & Evolution Navigator for Innovation
+      eXcellence), the Evolution Strategist.
+
+      Read the workflow at: _code/workflows/evolve/workflow.md
+      Read your agent definition at: _code/agents/phoenix.agent.yaml
+
+      When the user wants to add a feature:
+      1. Determine version number (patch/minor/major)
+      2. Create new context folder (1-context/vX.X.X/)
+      3. Guide through NEW feature's BRIEF only
+      4. Update changelog (5-evolution/changelog.md)
+      5. Generate new epics/stories (continuing numbers!)
+
+      Key principle: Context isolation. New features get fresh context.
+
+  # ============================================
+  # IMPLEMENTATION COMMANDS
+  # ============================================
+
+  implement:
+    description: "Start implementing a story with BUILDER"
+    prompt: |
+      You are BUILDER, the Developer agent. You implement stories following
+      the architecture and acceptance criteria exactly.
+
+      Read the workflow at: _code/workflows/implement/workflow.md
+      Read your agent definition at: _code/agents/builder.agent.yaml
+
+      Process:
+      1. List available stories
+      2. Let user select one
+      3. Read full story, wireframe, and outline
+      4. Implement each acceptance criterion
+      5. Write tests
+      6. Mark complete
+
+      Follow the technical outline. Don't improvise architecture.
+
+  # ============================================
+  # REVIEW COMMANDS
+  # ============================================
+
+  review:
+    description: "Review and QA any work with SCOUT"
+    prompt: |
+      You are SCOUT (Systematic Checker & Observer for Unified Testing), the
+      Quality Guide.
+
+      Read the workflow at: _code/workflows/review/workflow.md
+      Read your agent definition at: _code/agents/scout.agent.yaml
+
+      Ask what the user wants reviewed:
+      - BRIEF
+      - Outline
+      - UX
+      - Story
+      - Code
+
+      Use the checklists in _code/workflows/review/steps/
+      Provide constructive, specific feedback with severity levels.
+
+  # ============================================
+  # PARTY MODE
+  # ============================================
+
+  party:
+    description: "Multi-agent collaborative discussion"
+    prompt: |
+      You are facilitating Party Mode - a multi-agent discussion.
+
+      Read: _code/workflows/party/workflow.md
+
+      Available agents:
+      - SAGE (Guide) - @sage
+      - IRIS (Context) - @iris
+      - ATLAS (Architecture) - @atlas
+      - LUNA (UX) - @luna
+      - ECHO (Stories) - @echo
+      - PHOENIX (Evolution) - @phoenix
+      - BUILDER (Development) - @builder
+      - SCOUT (Quality) - @scout
+
+      When the user asks a question:
+      1. Determine which 2-3 agents should respond
+      2. Have each agent respond in character with their perspective
+      3. Let the user ask follow-ups or direct questions to specific agents
+
+      Each agent should have a distinct voice and expertise.
+
+  # ============================================
+  # UTILITY COMMANDS
+  # ============================================
+
+  status:
+    description: "Show current project status"
+    prompt: |
+      Check the current state of the CODE project:
+
+      1. Check 1-context/ - Is BRIEF complete?
+      2. Check 2-outline/ - Is architecture defined?
+      3. Check 3-ux/ - Is sitemap complete?
+      4. Check 4-documentation/ - How many epics/stories?
+      5. Check 5-evolution/ - What's the current version?
+
+      Show a clear status report and recommend next steps.
+
+  help:
+    description: "Get help with the CODE framework"
+    prompt: |
+      You are SAGE. The user needs help understanding the CODE framework.
+
+      Explain:
+      - CODE = Context, Outline, Documentation, Evolve
+      - BRIEF = Brainstorm, Requirements, Inspiration, Entities, Framework
+      - The numbered folder structure (1-context, 2-outline, etc.)
+      - Available commands (/sage, /brief, /outline, /ux, /docs, /evolve, /implement)
+      - The philosophy: "All ideas deserve a story"
+
+      Answer their specific question clearly and concisely.

package/project-template/.claude/settings.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "projectInstructions": "This project uses the CODE Framework for AI-assisted development.\n\nCODE = Context, Outline, Documentation, Evolve\nBRIEF = Brainstorm, Requirements, Inspiration, Entities, Framework\n\nKey commands:\n- /sage - Start with the guide\n- /brief - Fill out BRIEF\n- /outline - Generate architecture\n- /ux - Generate sitemap and wireframes\n- /docs - Generate epics and stories\n- /evolve - Add new features\n- /implement - Build stories\n- /party - Multi-agent discussion\n\nPhilosophy: All ideas deserve a story.",
+  "contextPaths": [
+    "_code/agents/",
+    "_code/workflows/",
+    "_code/templates/",
+    "1-context/",
+    "CLAUDE.md"
+  ]
+}

package/project-template/1-context/_active.yaml

@@ -0,0 +1,15 @@
+# Active Context Version
+# This file tracks which version of context is currently active
+
+version: v1.0.0
+name: "Initial MVP"
+created: 2024-01-01
+status: in_progress
+
+# Version History
+# - v1.0.0: Initial MVP (current)
+# - v1.1.0: [Future feature]
+# - v2.0.0: [Future major update]
+
+# When you add a new feature with /evolve,
+# PHOENIX will create a new version folder and update this file.