agentic-sdlc 1.0.0

package/bin/commands/install.js

@@ -0,0 +1,68 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { log } from '../utils/colors.js';
+
+/**
+ * Install instructions in current directory
+ */
+export async function install(templatePath, options = {}) {
+  const startTime = Date.now();
+  const targetPath = path.join(process.cwd(), '.agent');
+
+  try {
+    if (!options.quiet) log.header('🚀 Installing Template Instructions');
+
+    // Validate environment
+    if (options.verbose) log.step('Validating environment...');
+    if (!await fs.pathExists(templatePath)) {
+      throw new Error(`Template source not found at: ${templatePath}`);
+    }
+
+    // Check existing installation
+    if (!options.quiet) log.step('Checking for existing installation...');
+    if (await fs.pathExists(targetPath)) {
+      if (!options.force) {
+        log.warning('.agent directory already exists');
+        log.info('Use --force to overwrite existing files');
+        process.exit(0);
+      } else {
+        log.warning('Overwriting existing installation...');
+        await fs.remove(targetPath);
+      }
+    }
+
+    // Copy files
+    if (!options.quiet) log.step('Copying template files...');
+    await fs.copy(templatePath, targetPath, {
+      overwrite: options.force,
+      preserveTimestamps: true,
+    });
+
+    // Verify installation
+    if (options.verbose) {
+      log.step('Verifying installation...');
+      const files = await fs.readdir(targetPath, { recursive: true });
+      log.success(`Verified ${files.length} files installed`);
+    }
+
+    // Success message
+    if (!options.quiet) {
+      log.success('Installation complete!');
+      console.log(`Location: ${targetPath}`);
+      console.log(`\nNext Steps:`);
+      console.log('  • Setup IDE: agentic-sdlc ide cursor');
+      console.log('  • Review: .agent/usage.md');
+      console.log('  • Start: /pm Build your project\n');
+
+      const duration = ((Date.now() - startTime) / 1000).toFixed(2);
+      log.info(`Completed in ${duration}s`);
+    }
+
+    process.exit(0);
+  } catch (err) {
+    log.error('Installation failed');
+    log.error(err.message);
+    if (options.verbose) console.error('\nStack trace:', err.stack);
+    process.exit(1);
+  }
+}

package/bin/commands/list.js

@@ -0,0 +1,35 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { colors, log } from '../utils/colors.js';
+
+/**
+ * List available templates and roles
+ */
+export async function listTemplates(templatePath) {
+  try {
+    log.header('📋 Available Templates & Roles');
+
+    // List roles
+    const rolesPath = path.join(templatePath, 'roles');
+    const roles = await fs.readdir(rolesPath);
+    console.log(`${colors.bright}Roles (${roles.length}):${colors.reset}`);
+    roles.forEach(role => {
+      const roleName = role.replace('.md', '');
+      console.log(`  ${colors.green}•${colors.reset} ${roleName}`);
+    });
+
+    // List templates
+    const templatesPath = path.join(templatePath, 'templates');
+    const templates = await fs.readdir(templatesPath);
+    console.log(`\n${colors.bright}Templates (${templates.length}):${colors.reset}`);
+    templates.forEach(template => {
+      const templateName = template.replace('.md', '').replace('.json', '');
+      console.log(`  ${colors.blue}•${colors.reset} ${templateName}`);
+    });
+
+    console.log(`\n${colors.dim}Total: ${roles.length} roles, ${templates.length} templates${colors.reset}\n`);
+  } catch (err) {
+    log.error(`Failed to list templates: ${err.message}`);
+    process.exit(1);
+  }
+}

package/bin/graph_brain.py

@@ -0,0 +1,86 @@
+import os
+import glob
+from neo4j import GraphDatabase
+from dotenv import load_dotenv
+
+# Load environment variables
+load_dotenv()
+
+URI = os.getenv("NEO4J_URI")
+USERNAME = os.getenv("NEO4J_USERNAME")
+PASSWORD = os.getenv("NEO4J_PASSWORD")
+
+class Neo4jBrain:
+    def __init__(self, uri, user, password):
+        self.driver = GraphDatabase.driver(uri, auth=(user, password))
+
+    def close(self):
+        self.driver.close()
+
+    def initialize_schema(self):
+        with self.driver.session() as session:
+            # Create constraints
+            session.run("CREATE CONSTRAINT IF NOT EXISTS FOR (f:File) REQUIRE f.path IS UNIQUE")
+            session.run("CREATE CONSTRAINT IF NOT EXISTS FOR (r:Requirement) REQUIRE r.id IS UNIQUE")
+            session.run("CREATE CONSTRAINT IF NOT EXISTS FOR (i:Issue) REQUIRE i.number IS UNIQUE")
+            session.run("CREATE CONSTRAINT IF NOT EXISTS FOR (ro:Role) REQUIRE ro.name IS UNIQUE")
+            print("[SUCCESS] Neo4j Schema Initialized")
+
+    def ingest_project_structure(self, base_path):
+        """Walks the directory and creates File nodes and directory HIERARCHY."""
+        with self.driver.session() as session:
+            # Ignore some directories
+            ignore_dirs = {'.git', 'node_modules', '.agent', '__pycache__'}
+            
+            for root, dirs, files in os.walk(base_path):
+                # Filter ignore dirs
+                dirs[:] = [d for d in dirs if d not in ignore_dirs]
+                
+                rel_root = os.path.relpath(root, base_path)
+                if rel_root == ".": rel_root = "root"
+                
+                for file in files:
+                    rel_path = os.path.relpath(os.path.join(root, file), base_path)
+                    ext = os.path.splitext(file)[1]
+                    
+                    session.run("""
+                        MERGE (f:File {path: $path})
+                        SET f.name = $name, f.extension = $ext, f.last_updated = timestamp()
+                        MERGE (d:Directory {path: $dir})
+                        MERGE (d)-[:CONTAINS]->(f)
+                    """, path=rel_path, name=file, ext=ext, dir=rel_root)
+        print(f"[SUCCESS] Ingested project structure from {base_path}")
+
+    def link_issue_to_file(self, issue_number, file_path, rel_type="AFFECTS"):
+        with self.driver.session() as session:
+            session.run(f"""
+                MERGE (i:Issue {{number: $issue_num}})
+                MERGE (f:File {{path: $file_path}})
+                MERGE (i)-[:{rel_type}]->(f)
+            """, issue_num=issue_number, file_path=file_path)
+
+    def get_context_for_file(self, file_path):
+        """Retrieves related requirements and issues for a file."""
+        with self.driver.session() as session:
+            result = session.run("""
+                MATCH (f:File {path: $path})
+                OPTIONAL MATCH (i:Issue)-[r1]->(f)
+                OPTIONAL MATCH (req:Requirement)-[r2]->(f)
+                RETURN f.path as path, collect(DISTINCT i.number) as issues, collect(DISTINCT req.id) as requirements
+            """, path=file_path)
+            return result.single()
+
+if __name__ == "__main__":
+    if not URI or not PASSWORD:
+        print("[ERROR] NEO4J_URI or NEO4J_PASSWORD not found in .env")
+    else:
+        brain = Neo4jBrain(URI, USERNAME, PASSWORD)
+        try:
+            brain.initialize_schema()
+            # Ingest current directory
+            brain.ingest_project_structure(".")
+            print("[SUCCESS] Project brain is now updated in the cloud.")
+        except Exception as e:
+            print(f"[ERROR] Operation failed: {e}")
+        finally:
+            brain.close()

package/bin/sync_github.py

@@ -0,0 +1,75 @@
+import os
+import re
+from github import Github
+from neo4j import GraphDatabase
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# Config
+URI = os.getenv("NEO4J_URI")
+USERNAME = os.getenv("NEO4J_USERNAME")
+PASSWORD = os.getenv("NEO4J_PASSWORD")
+GITHUB_TOKEN = os.getenv("GITHUB_TOKEN")
+GITHUB_REPO = os.getenv("GITHUB_REPO")
+
+class GitHubNeo4jBridge:
+    def __init__(self):
+        if not all([URI, USERNAME, PASSWORD, GITHUB_TOKEN, GITHUB_REPO]):
+            raise Exception("Missing environment variables in .env")
+        self.driver = GraphDatabase.driver(URI, auth=(USERNAME, PASSWORD))
+        self.github = Github(GITHUB_TOKEN)
+        self.repo = self.github.get_repo(GITHUB_REPO)
+
+    def close(self):
+        self.driver.close()
+
+    def sync_issues(self):
+        print(f"🚀 Syncing issues from {GITHUB_REPO}...")
+        issues = self.repo.get_issues(state='all')
+        
+        with self.driver.session() as session:
+            for issue in issues:
+                print(f"Processing Issue #{issue.number}: {issue.title}")
+                
+                # 1. Create/Update Issue Node
+                session.run("""
+                    MERGE (i:Issue {number: $number})
+                    SET i.title = $title, i.state = $state, i.url = $url, i.body = $body
+                """, number=issue.number, title=issue.title, state=issue.state, url=issue.html_url, body=issue.body)
+
+                # 2. Extract Labels
+                for label in issue.labels:
+                    session.run("""
+                        MATCH (i:Issue {number: $number})
+                        MERGE (l:Label {name: $label_name})
+                        SET l.color = $color
+                        MERGE (i)-[:HAS_LABEL]->(l)
+                    """, number=issue.number, label_name=label.name, color=label.color)
+
+                # 3. Simple Heuristic: Link to Files mentioned in body
+                if issue.body:
+                    # Look for paths like d:\dev\... or just relative paths mentioned
+                    # This regex looks for common file extensions in the body
+                    paths = re.findall(r'[\w\-\.\/]+\.(?:py|js|ts|md|yml|json|md)', issue.body)
+                    for path in set(paths):
+                        # Clean up path from some markdown characters
+                        clean_path = path.strip('`()[]')
+                        
+                        # Try to match existing File nodes in Neo4j
+                        session.run("""
+                            MATCH (i:Issue {number: $number})
+                            MATCH (f:File)
+                            WHERE f.path ENDS WITH $path OR $path ENDS WITH f.path
+                            MERGE (i)-[:RELATES_TO_FILE]->(f)
+                        """, number=issue.number, path=clean_path)
+
+        print("[SUCCESS] GitHub Issues synced to Neo4j Cloud.")
+
+if __name__ == "__main__":
+    try:
+        bridge = GitHubNeo4jBridge()
+        bridge.sync_issues()
+        bridge.close()
+    except Exception as e:
+        print(f"[ERROR] {e}")

package/bin/utils/args-parser.js

@@ -0,0 +1,33 @@
+/**
+ * Parse command line arguments
+ */
+export function parseArgs(args) {
+  const options = {
+    force: false,
+    quiet: false,
+    verbose: false,
+    noColor: false,
+  };
+
+  const filtered = args.filter(arg => {
+    if (arg === '-f' || arg === '--force') {
+      options.force = true;
+      return false;
+    }
+    if (arg === '-q' || arg === '--quiet') {
+      options.quiet = true;
+      return false;
+    }
+    if (arg === '--verbose') {
+      options.verbose = true;
+      return false;
+    }
+    if (arg === '--no-color') {
+      options.noColor = true;
+      return false;
+    }
+    return true;
+  });
+
+  return { options, args: filtered };
+}

package/bin/utils/colors.js

@@ -0,0 +1,21 @@
+// ANSI color codes
+export const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  magenta: '\x1b[35m',
+};
+
+export const log = {
+  info: (msg) => console.log(`${colors.cyan}ℹ${colors.reset} ${msg}`),
+  success: (msg) => console.log(`${colors.green}✓${colors.reset} ${msg}`),
+  warning: (msg) => console.log(`${colors.yellow}⚠${colors.reset} ${msg}`),
+  error: (msg) => console.error(`${colors.red}✗${colors.reset} ${msg}`),
+  step: (msg) => console.log(`${colors.blue}→${colors.reset} ${msg}`),
+  header: (msg) => console.log(`\n${colors.bright}${msg}${colors.reset}\n`),
+};

package/bin/verify_neo4j.py

@@ -0,0 +1,25 @@
+import os
+from neo4j import GraphDatabase
+from dotenv import load_dotenv
+
+load_dotenv()
+
+URI = os.getenv("NEO4J_URI")
+USERNAME = os.getenv("NEO4J_USERNAME")
+PASSWORD = os.getenv("NEO4J_PASSWORD")
+
+def verify_data():
+    driver = GraphDatabase.driver(URI, auth=(USERNAME, PASSWORD))
+    with driver.session() as session:
+        result = session.run("MATCH (f:File) RETURN f.path as path, f.summary as summary")
+        records = list(result)
+        if records:
+            print(f"[SUCCESS] Found {len(records)} files in Neo4j:")
+            for record in records:
+                print(f" - {record['path']}: {record['summary']}")
+        else:
+            print("[WARNING] No files found in Neo4j.")
+    driver.close()
+
+if __name__ == "__main__":
+    verify_data()

package/docs/OUTLINE.md

@@ -0,0 +1,23 @@
+# Documentation Outline
+
+Explore the comprehensive documentation for Agentic SDLC to master its specialized AI roles and automated workflows.
+
+## 🚀 Getting Started
+- **[Quick Start Guide](guides/QUICK-START.md)**: Get up and running in 5 minutes.
+- **[Integration Guide](guides/INTEGRATION-GUIDE.md)**: Add Agentic SDLC to your existing projects.
+- **[CLI Examples](guides/CLI-EXAMPLES.md)**: Real-world command-line usage and workflows.
+
+## 🛠️ Core Concepts
+- **[Usage Guide](../.agent/usage.md)**: Detailed documentation on roles, modes, and commands.
+- **[IDE Integration](../.agent/ide-integration/README.md)**: Setting up Cursor, Copilot, and other IDEs.
+- **[MCP Guide](guides/MCP-GUIDE.md)**: Understanding Model Context Protocol (MCP) integrations.
+
+## 🏛️ Architecture & Knowledge
+- **[AI Brain](architecture/brain.md)**: How the project captures and uses collective knowledge.
+- **[Neo4j Queries](architecture/neo4j-learning-queries.md)**: Advanced knowledge retrieval for technical insights.
+
+## ⚙️ Project Management
+- **[GitHub Management](setup/github-management.md)**: Integrating with GitHub issues and automation.
+
+---
+*Generated by Antigravity - 2026-01-01*

package/docs/architecture/brain.md

@@ -0,0 +1,36 @@
+# 🧠 The Project Brain: Hybrid Memory & Reasoning
+
+This project uses a **Hybrid Brain Architecture** combining **LEANN** (Vector Memory) and **Neo4j Aura** (Reasoning Graph).
+
+## 🚀 Two Layers of Intelligence
+
+### 1. LEANN (Semantic Knowledge)
+- **Primary Use:** Finding similar code patterns and semantic context.
+- **Why:** Ultra-fast, AST-aware search with 97% storage savings.
+- **Operation:** Local (runs via WSL2 or local Python).
+
+### 2. Neo4j Cloud (Reasoning Graph)
+- **Primary Use:** Understanding relationships between requirements, code, and bugs.
+- **Why:** Allows agents to perform deep reasoning paths: *"This bug in File X is related to Requirement Y implemented in Sprint Z."*
+- **Operation:** Cloud-based (Neo4j AuraDB).
+
+## 🛠️ How to Use
+
+### 1. Semantic Search
+Use `/brain [query]` or run:
+```bash
+leann search "your query"
+```
+
+### 2. Reasoning Update
+To sync the latest project structure and relationships to the Cloud Brain:
+```bash
+python bin/graph_brain.py
+```
+
+## 📋 Best Practices
+- **Update Frequently:** Run the ingestion script after merging any major feature.
+- **Hybrid Queries:** When solving a complex bug, ask the AI to check both LEANN for code context and Neo4j for relationship history.
+
+---
+*Powered by [LEANN](https://github.com/yichuan-w/LEANN) and [Neo4j Aura](https://neo4j.com/aura/)*

package/docs/architecture/neo4j-learning-queries.md

@@ -0,0 +1,49 @@
+# 🧠 AI Self-Learning: Neo4j Reasoning Dashboard
+
+These Cypher queries are designed to help the AI (and you) extract "wisdom" from the project graph. Run these in your [Neo4j Aura Console](https://console.neo4j.io/).
+
+## 1. 📂 Project Heatmap (Risk Analysis)
+Find files that are frequently linked to bugs. These are your "high-risk" areas that require more testing.
+```cypher
+MATCH (f:File)<-[:RELATES_TO_FILE]-(i:Issue)-[:HAS_LABEL]->(l:Label {name: 'type:bug'})
+RETURN f.path AS FilePath, count(i) AS BugCount
+ORDER BY BugCount DESC
+LIMIT 10
+```
+
+## 2. 🕵️ Feature Lineage
+Trace a specific feature requirement to the exact files that implement it and the issues encountered during development.
+```cypher
+MATCH (f:File)<-[:RELATES_TO_FILE]-(i:Issue)
+WHERE i.title CONTAINS 'Feature Name'  // Replace with your feature
+RETURN i.number AS Issue, i.title AS Title, f.path AS AffectedFile
+```
+
+## 3. 🚦 Skill Capability Map
+See which roles (labels) are managing which parts of the codebase. This helps in understanding "Who owns what?"
+```cypher
+MATCH (f:File)<-[:RELATES_TO_FILE]-(i:Issue)-[:HAS_LABEL]->(l:Label)
+WHERE l.name STARTS WITH 'role:'
+RETURN l.name AS Role, f.path AS FilePath, count(i) AS ContributionLevel
+ORDER BY ContributionLevel DESC
+```
+
+## 4. 🧠 The "Lessons Learned" Path
+Find the reasoning body for completed tasks to help the AI implement similar features in the future.
+```cypher
+MATCH (i:Issue {state: 'closed'})-[:RELATES_TO_FILE]->(f:File)
+RETURN i.title AS TaskSummary, i.body AS TechnicalReasoning, f.path AS ReferenceFile
+ORDER BY i.number DESC
+LIMIT 5
+```
+
+## 🧹 Maintenance Query: Clean Up Unlinked Files
+Find files that don't have any issue coverage yet (potentially dark code).
+```cypher
+MATCH (f:File)
+WHERE NOT (f)<-[:RELATES_TO_FILE]-(:Issue)
+RETURN f.path AS UntrackedFile
+```
+
+---
+*Query these regularly to improve the AI's "Intuition" about the codebase.*