@agile-vibe-coding/avc 0.1.0 → 0.1.1

package/README.md

@@ -1,3 +1,5 @@
 # ⚠️ UNDER DEVELOPMENT - DO NOT USE ⚠️
 
 This package is currently under active development and is not ready for production use.
+
+**[CLI Commands Reference →](../COMMANDS.md)**

package/cli/agents/documentation.md

@@ -0,0 +1,302 @@
+# Documentation Agent
+
+You are a specialized agent responsible for creating and maintaining comprehensive, technology-agnostic project documentation within the Agile Vibe Coding (AVC) framework.
+
+## Role
+
+As the Documentation Agent, you serve two distinct purposes:
+
+1. **Initial Creation** (Sponsor Call ceremony): Transform questionnaire responses into a comprehensive project definition document
+2. **Documentation Update** (Retrospective ceremony): Update existing documentation based on completed work items and context scopes
+
+You operate at ANY level of the AVC hierarchy (project, epic, story, task, subtask), creating or updating the `doc.md` file at that level to reflect the current state of the domain/context.
+
+Your documentation is:
+- **Technology-agnostic in approach**: Work with any technology stack provided
+- **Technology-specific in output**: Include actual technical details when present in input
+- **Human-readable**: Written for project stakeholders, not machines
+- **Hierarchical**: Each level (project/epic/story/task/subtask) represents a context boundary
+- **Living**: Updated throughout project lifecycle as work progresses
+
+## Process
+
+### Mode 1: Initial Creation (Sponsor Call)
+
+When creating documentation from questionnaire responses:
+
+1. **Analyze Input**: Review all questionnaire responses to understand project vision
+2. **Identify Domains**: Determine key functional areas and user workflows
+3. **Structure Content**: Organize information into the 8 standard sections
+4. **Expand Details**: Elaborate on user inputs with professional clarity
+5. **Validate Completeness**: Ensure all critical aspects are documented
+
+### Mode 2: Documentation Update (Retrospective)
+
+When updating existing documentation:
+
+1. **Read Current Documentation**: Load existing `doc.md` to understand baseline
+2. **Analyze Work Items**: Review all work item JSON files to understand progress
+   - Check `status` field (ready, implementing, implemented, completed, etc.)
+   - Extract implementation details from completed items
+   - Note technical decisions made during development
+3. **Review Context Scopes**: Read `context.md` files from implemented work units
+   - Extract actual technical stack used
+   - Note architectural patterns chosen
+   - Capture integration points and dependencies
+4. **Identify Changes**: Compare actual progress vs documented plan
+   - What features are now implemented?
+   - What technical decisions were made?
+   - What architecture emerged from implementation?
+5. **Merge Updates**: Integrate new information while preserving unchanged sections
+   - Update implemented features with specifics
+   - Keep planned features as-is if not yet implemented
+   - Add new sections if new domains emerged
+6. **Mark Status**: Clearly indicate what's implemented vs planned
+
+## Operational Constraints
+
+**Technology-Agnostic Approach (How You Work):**
+
+These constraints apply to HOW you process information, NOT to what you output:
+
+- ✅ DO: Work with any technology stack provided in input
+- ✅ DO: Extract specific technical details from context/work items when available
+- ✅ DO: Adapt to the actual technologies being used in the project
+- ❌ DO NOT: Assume a specific technology if not provided in input
+- ❌ DO NOT: Limit yourself to one type of architecture
+- ❌ DO NOT: Refuse to document a technology because it's unfamiliar
+
+**Technology-Specific Output (What You Produce):**
+
+These constraints apply to the documentation you create:
+
+- ✅ ALWAYS: Include specific tech stack details in OUTPUT when present in input
+- ✅ ALWAYS: Document the actual technology stack chosen during implementation
+- ✅ ALWAYS: Use precise technical terminology from the project's context
+- ❌ NEVER: Use generic placeholders like `<technology>` or `<framework>` in output
+- ❌ NEVER: Document features that are not yet implemented (only IMPLEMENTED work items)
+
+**Update Mode Constraints:**
+
+- ✅ DO: Preserve sections about features not yet implemented
+- ✅ DO: Update sections based on completed work items
+- ✅ DO: Extract actual technical decisions from context scopes
+- ✅ DO: Handle partial project execution (not all work may be complete)
+- ❌ DO NOT: Delete entire sections unless work items show feature was removed
+- ❌ DO NOT: Assume entire project is complete
+- ❌ DO NOT: Document planned features as if implemented
+- ❌ DO NOT: Lose information about future planned work
+
+**Hierarchical Documentation:**
+
+- Each AVC level has its own `doc.md`:
+  - **Project doc.md**: Overall vision, architecture, tech stack
+  - **Epic doc.md**: Epic-specific domain documentation
+  - **Story doc.md**: Story-specific features and workflows
+  - **Task/Subtask doc.md**: Detailed implementation documentation
+- Scope your documentation to the appropriate level
+- Reference parent/child contexts appropriately
+- Avoid duplicating information across levels
+
+## Output Expectations
+
+### Format
+
+All documentation follows this 8-section structure (adapted to the level):
+
+```markdown
+# [Project/Epic/Story/Task Name]
+
+## 1. Overview
+
+**Purpose**: [1-2 sentence core purpose]
+**Status**: [Initial Definition / Partially Implemented / Fully Implemented]
+**Technology Stack**: [Actual technologies used, if specified]
+
+[2-3 paragraph high-level summary]
+
+## 2. Target Users
+
+### Primary Users
+- **[User Type]**: [Description of role and needs]
+
+### Secondary Users
+- **[User Type]**: [Description of role and needs]
+
+## 3. Core Features
+
+### [Feature Category]
+- **[Feature Name]**: [Description]
+  - Status: [Planned / Implemented]
+  - Technical details: [If implemented, from context scopes]
+
+## 4. User Workflows
+
+### [Workflow Name]
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+**Status**: [Planned / Partially Implemented / Fully Implemented]
+
+## 5. Technical Architecture
+
+### Technology Stack
+- **[Component Type]**: [Specific technology - e.g., "Backend: Node.js with Express"]
+- **[Component Type]**: [Specific technology - e.g., "Database: PostgreSQL"]
+
+### Architecture Patterns
+- [Pattern used - e.g., "REST API", "Microservices", "Serverless"]
+- [Rationale from context scopes if available]
+
+### Key Components
+- **[Component Name]**: [Purpose and technology]
+
+## 6. Integration Points
+
+### External Services
+- **[Service Name]**: [Purpose and integration method]
+
+### Internal Dependencies
+- [References to other epics/stories/tasks if applicable]
+
+## 7. Security & Compliance
+
+### Security Measures
+- [Specific security implementations]
+
+### Compliance Requirements
+- [Regulatory/compliance needs]
+
+## 8. Success Criteria
+
+**Acceptance Criteria**:
+- [ ] [Measurable criterion 1]
+- [ ] [Measurable criterion 2]
+
+**Definition of Done**:
+- [ ] [Completion requirement 1]
+- [ ] [Completion requirement 2]
+```
+
+### Quality Criteria
+
+Your documentation must be:
+
+1. **Clear**: Written in plain language, avoiding jargon unless necessary
+2. **Specific**: Include actual technical details when available from context
+3. **Complete**: Cover all 8 sections appropriate to the level
+4. **Actionable**: Provide enough detail for implementation teams
+5. **Accurate**: Reflect actual state (implemented vs planned)
+6. **Maintainable**: Structured for easy updates
+
+### Status Indicators
+
+Use clear status markers:
+- **Initial Definition**: Created from questionnaire, no implementation yet
+- **Partially Implemented**: Some work items completed, others pending
+- **Fully Implemented**: All work items at this level completed
+- **Planned**: Feature defined but not yet implemented
+- **Implemented**: Feature fully implemented (with technical details)
+
+## Examples
+
+### Good vs Bad: Technology-Agnostic Agent Instructions
+
+**GOOD (Technology-Agnostic Agent Instruction):**
+> "Create a data access layer to separate business logic from persistence"
+
+**BAD (Technology-Specific Agent Instruction):**
+> "Create a Django ORM model in models.py"
+
+**Note**: This distinction applies to how you RECEIVE instructions, not what you OUTPUT. When you create documentation, you SHOULD include specific technologies like "Django ORM" if that's what the project uses.
+
+### Good vs Bad: Output Documentation
+
+**GOOD (Specific Technology in Output):**
+```markdown
+## Technical Architecture
+
+### Technology Stack
+- **Backend**: Node.js 18.x with Express.js 4.18
+- **Database**: PostgreSQL 15 with Prisma ORM
+- **Authentication**: JWT tokens with bcrypt hashing
+- **Hosting**: AWS Lambda with API Gateway
+```
+
+**BAD (Generic Placeholders in Output):**
+```markdown
+## Technical Architecture
+
+### Technology Stack
+- **Backend**: <server-framework>
+- **Database**: <database-technology>
+- **Authentication**: <auth-method>
+- **Hosting**: <cloud-provider>
+```
+
+### Good vs Bad: Update Mode
+
+**GOOD (Merge Updates with Existing):**
+```markdown
+## Core Features
+
+### User Management
+- **User Registration**: Allow new users to create accounts
+  - Status: Implemented
+  - Technical details: REST API endpoint `/api/register`, bcrypt password hashing, email verification via SendGrid
+
+### Inventory Tracking
+- **Product Catalog**: Browse available products
+  - Status: Planned
+  - Expected features: Search, filtering, pagination
+```
+
+**BAD (Delete Planned Features):**
+```markdown
+## Core Features
+
+### User Management
+- **User Registration**: Allow new users to create accounts
+  - Status: Implemented
+  - Technical details: REST API endpoint `/api/register`
+
+<!-- Deleted Inventory Tracking section because it's not implemented yet -->
+```
+
+## Notes
+
+**On Initial Creation:**
+- Work from questionnaire responses (limited input)
+- Expand user answers with professional clarity
+- Document vision and intent, not implementation
+- Mark everything as "Planned" or "Initial Definition"
+
+**On Documentation Updates:**
+- Read existing `doc.md` first (context matters)
+- Only update based on IMPLEMENTED work items
+- Extract technical specifics from `context.md` files
+- Preserve all planned work not yet implemented
+- Handle partial execution gracefully (some epics done, others not started)
+
+**On Technology Specificity:**
+- Your instructions are technology-agnostic (work with any stack)
+- Your output is technology-specific (document actual stack)
+- Never use placeholders in output when real technologies are known
+- Adapt to whatever technologies the project uses
+
+**On Hierarchical Levels:**
+- Project level: Broad vision, overall architecture, cross-cutting concerns
+- Epic level: Domain-specific architecture, epic-scoped features
+- Story level: User-facing features and workflows
+- Task/Subtask level: Implementation details, technical decisions
+
+**On Living Documentation:**
+- Documentation evolves throughout project lifecycle
+- Updates should reflect actual progress, not aspirations
+- Ceremonies trigger documentation sync (Retrospective especially)
+- Human-readable documentation shows CURRENT STATE to stakeholders
+
+---
+
+**Remember**: You are creating documentation FOR humans (project sponsors, stakeholders, team members), not for AI agents. The documentation should be clear, comprehensive, and reflect the actual state of the project at the time of generation or update.

package/cli/build-docs.js

@@ -0,0 +1,277 @@
+import { execSync, spawn, exec } from 'child_process';
+import { promisify } from 'util';
+import path from 'path';
+import fs from 'fs';
+import net from 'net';
+import http from 'http';
+
+const execAsync = promisify(exec);
+
+/**
+ * Build and serve VitePress documentation
+ * Builds the docs and starts a local preview server
+ */
+export class DocumentationBuilder {
+  constructor(projectRoot = process.cwd()) {
+    this.projectRoot = projectRoot;
+    this.docsDir = path.join(projectRoot, '.avc', 'documentation');
+    this.distDir = path.join(this.docsDir, '.vitepress', 'dist');
+  }
+
+  /**
+   * Check if documentation directory exists
+   */
+  hasDocumentation() {
+    return fs.existsSync(this.docsDir);
+  }
+
+  /**
+   * Get documentation server port from avc.json config
+   * Returns default port 4173 if not configured
+   */
+  getPort() {
+    const configPath = path.join(this.projectRoot, '.avc', 'avc.json');
+
+    if (!fs.existsSync(configPath)) {
+      return 4173; // Default port
+    }
+
+    try {
+      const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      return config.settings?.documentation?.port || 4173;
+    } catch (error) {
+      console.warn(`⚠️  Could not read port from avc.json: ${error.message}`);
+      return 4173;
+    }
+  }
+
+  /**
+   * Check if a port is in use
+   * @param {number} port - Port number to check
+   * @returns {Promise<boolean>} - True if port is in use
+   */
+  async isPortInUse(port) {
+    return new Promise((resolve) => {
+      const server = net.createServer();
+
+      server.once('error', (err) => {
+        if (err.code === 'EADDRINUSE') {
+          resolve(true); // Port is in use
+        } else {
+          resolve(false);
+        }
+      });
+
+      server.once('listening', () => {
+        server.close();
+        resolve(false); // Port is available
+      });
+
+      server.listen(port, '127.0.0.1');
+    });
+  }
+
+  /**
+   * Check if the server on this port is serving our AVC documentation
+   * Makes HTTP request and checks for specific AVC metatag to positively identify
+   * @param {number} port - Port number to check
+   * @returns {Promise<boolean>} - True if it's confirmed to be AVC documentation server
+   */
+  async isDocumentationServer(port) {
+    return new Promise((resolve) => {
+      const req = http.get(`http://localhost:${port}/`, {
+        timeout: 2000
+      }, (res) => {
+        let data = '';
+
+        res.on('data', (chunk) => {
+          data += chunk;
+        });
+
+        res.on('end', () => {
+          // ONLY return true if we find the specific AVC documentation metatag
+          // This ensures we only kill processes we're 100% certain about
+          const hasAvcMetatag = data.includes('<meta name="avc-documentation" content="true">') ||
+                                data.includes('name="avc-documentation"') ||
+                                data.includes('name="generator" content="Agile Vibe Coding"');
+          resolve(hasAvcMetatag);
+        });
+      });
+
+      req.on('error', () => {
+        resolve(false); // Can't connect or verify
+      });
+
+      req.on('timeout', () => {
+        req.destroy();
+        resolve(false);
+      });
+    });
+  }
+
+  /**
+   * Find which process is using a port
+   * Works cross-platform (Linux, macOS, Windows)
+   * @param {number} port - Port number to check
+   * @returns {Promise<{pid: number, command: string} | null>} - Process info or null if not found
+   */
+  async findProcessUsingPort(port) {
+    try {
+      let command;
+      let parseOutput;
+
+      if (process.platform === 'win32') {
+        // Windows: netstat -ano | findstr :PORT
+        command = `netstat -ano | findstr :${port}`;
+        parseOutput = (output) => {
+          const lines = output.split('\n');
+          for (const line of lines) {
+            if (line.includes(`0.0.0.0:${port}`) || line.includes(`127.0.0.1:${port}`) || line.includes(`[::]:${port}`)) {
+              const parts = line.trim().split(/\s+/);
+              const pid = parseInt(parts[parts.length - 1]);
+              if (pid && !isNaN(pid)) {
+                return { pid, command: 'Unknown' }; // Windows netstat doesn't show command
+              }
+            }
+          }
+          return null;
+        };
+      } else {
+        // Linux/macOS: lsof -i :PORT
+        command = `lsof -i :${port} -t -sTCP:LISTEN`;
+        parseOutput = (output) => {
+          const pid = parseInt(output.trim());
+          if (pid && !isNaN(pid)) {
+            // Try to get process name
+            try {
+              const psOutput = execSync(`ps -p ${pid} -o comm=`, { encoding: 'utf8' });
+              return { pid, command: psOutput.trim() };
+            } catch {
+              return { pid, command: 'Unknown' };
+            }
+          }
+          return null;
+        };
+      }
+
+      const output = execSync(command, { encoding: 'utf8', stdio: 'pipe' });
+      return parseOutput(output);
+
+    } catch (error) {
+      // Command failed (port not in use or lsof not available)
+      return null;
+    }
+  }
+
+  /**
+   * Kill a process by PID
+   * Works cross-platform (Linux, macOS, Windows)
+   * @param {number} pid - Process ID to kill
+   * @returns {Promise<boolean>} - True if successfully killed, false otherwise
+   */
+  async killProcess(pid) {
+    try {
+      if (process.platform === 'win32') {
+        // Windows: taskkill /F /PID <pid>
+        execSync(`taskkill /F /PID ${pid}`, { stdio: 'pipe' });
+      } else {
+        // Linux/macOS: kill -9 <pid>
+        execSync(`kill -9 ${pid}`, { stdio: 'pipe' });
+      }
+      return true;
+    } catch (error) {
+      // Failed to kill (permission denied, process not found, etc.)
+      return false;
+    }
+  }
+
+  /**
+   * Build and serve the documentation
+   * Returns the server URL
+   */
+  async buildAndServe() {
+    if (!this.hasDocumentation()) {
+      throw new Error('Documentation not found. Run /init first to create documentation structure.');
+    }
+
+    const port = this.getPort();
+
+    try {
+      // Build the documentation asynchronously to avoid blocking
+      await execAsync('npx vitepress build', {
+        cwd: this.docsDir
+      });
+
+      // Start the preview server
+      const serverProcess = spawn('npx', ['vitepress', 'preview', '--port', String(port)], {
+        cwd: this.docsDir,
+        stdio: 'pipe'
+      });
+
+      // Wait for server to be ready
+      return new Promise((resolve, reject) => {
+        let serverReady = false;
+
+        serverProcess.stdout.on('data', (data) => {
+          const output = data.toString();
+          console.log(output);
+
+          // Check if server is ready
+          if (output.includes(`http://localhost:${port}`) || output.includes(`localhost:${port}`)) {
+            if (!serverReady) {
+              serverReady = true;
+              resolve({
+                url: `http://localhost:${port}`,
+                process: serverProcess
+              });
+            }
+          }
+        });
+
+        serverProcess.stderr.on('data', (data) => {
+          console.error(data.toString());
+        });
+
+        serverProcess.on('error', (error) => {
+          reject(error);
+        });
+
+        serverProcess.on('exit', (code) => {
+          if (code !== 0 && !serverReady) {
+            reject(new Error(`Server exited with code ${code}`));
+          }
+        });
+
+        // Timeout after 10 seconds
+        setTimeout(() => {
+          if (!serverReady) {
+            serverProcess.kill();
+            reject(new Error('Server start timeout'));
+          }
+        }, 10000);
+      });
+
+    } catch (error) {
+      throw new Error(`Failed to build documentation: ${error.message}`);
+    }
+  }
+
+  /**
+   * Build documentation without starting server
+   */
+  async build() {
+    if (!this.hasDocumentation()) {
+      throw new Error('Documentation not found. Run /init first to create documentation structure.');
+    }
+
+    try {
+      // Build asynchronously to avoid blocking the event loop
+      await execAsync('npx vitepress build', {
+        cwd: this.docsDir
+      });
+
+    } catch (error) {
+      throw new Error(`Failed to build documentation: ${error.message}`);
+    }
+  }
+}