agentic-code 0.5.1

package/AGENTS.md

@@ -0,0 +1,156 @@
+# AGENTS.md
+
+## ABSOLUTE PRINCIPLES
+
+1. **EXECUTE all rules and requirements in task/rule files - no exceptions**
+2. **COMPLETE all entry and exit conditions for every task**
+3. **STOP at gates - proceed only when conditions are met**
+
+## Initial Setup [FIRST TIME ONLY]
+
+**Complete before any other operation:**
+1. Execute `date` command → Store as SESSION_BASELINE_DATE
+2. Apply `.agents/rules/core/metacognition.md` → Keep active entire session
+3. Use SESSION_BASELINE_DATE for all date references (WebSearch, docs, etc.)
+4. Verify project structure with `ls -la`
+
+## Core Execution Principle
+
+**Universal Entry Point**: Every request starts with task-analysis.md to determine the appropriate path.
+
+## Task Analysis - Required First Step
+
+**ALWAYS start here for any user request:**
+1. Apply `.agents/tasks/task-analysis.md`
+2. Follow its output to select the appropriate path:
+
+### Path Selection Based on Task Analysis
+
+**Small Scale (1-2 files) / Single Task:**
+- Load specific task definition (e.g., implementation.md, technical-design.md)
+- Execute that task definition directly
+- No workflow needed
+
+**Medium/Large Scale (3+ files) / Complex Task:**
+- Follow task-analysis.md recommendation for workflow selection
+
+## Core Principles
+
+### Plan Injection [MANDATORY ENFORCEMENT]
+**All tasks require Plan Injection for BLOCKING READs:**
+- Task-analysis.md Step 8 scans and identifies ALL BLOCKING READ requirements
+- Work plans MUST contain every BLOCKING READ from workflow/tasks/rules
+- Each phase verifies its BLOCKING READs are in the plan
+- Gates verify Plan Injection evidence before proceeding
+- Missing ANY BLOCKING READ = IMMEDIATE HALT
+
+### Task Definition Loading
+**Task definitions define WHAT to build - never skip them:**
+- Verify entry gates before proceeding
+- Follow Required Rules section in each task definition
+
+### Rule Application
+**Apply rules based on task type from task-analysis:**
+- Rules are loaded progressively as needed
+- Each task definition specifies its required rules
+- Unload task-specific rules after completion
+
+### Quality Standards
+**Before marking any task complete:**
+- All tests pass (when applicable)
+- All quality checks return 0 errors
+- Task exit conditions are satisfied
+- Work documented as needed
+
+## Approval Points
+
+**Principle**: Get user approval at significant milestones.
+
+Common approval points:
+- When recommending a workflow for Medium/Large tasks
+- After creating design or decision documents
+- When technical approach changes significantly
+- At task definition specified stop points
+
+**VIOLATIONS TO PREVENT:**
+- Work plan without ALL BLOCKING READs = RETURN TO TASK ANALYSIS
+- Skipping ANY BLOCKING READ = IMMEDIATE HALT
+- Proceeding without task definition compliance = BLOCKING ERROR
+
+## Quality Standards
+
+**Universal quality requirements:**
+- Follow TDD process for all code changes
+- All quality checks must pass with 0 errors
+- Follow standards defined in language-specific rules
+- Each task definition specifies its quality gates
+
+## Metacognition Checkpoints
+
+Perform self-assessment at these mandatory points:
+- Task type changes
+- Unexpected errors occur
+- Completing a meaningful unit of work
+- Before starting new implementation
+- After completing each task from work plan
+
+## Context Management
+
+**Guidelines**:
+- Load rules progressively, not all at once
+- Unload task-specific rules after completion
+- Keep only frequently-used rules loaded
+- If context feels constrained, ask user for cleanup guidance
+
+## Error Recovery
+
+When stuck or encountering errors:
+1. Re-read current task definition
+2. Check if required rules are loaded
+3. Look for anti-patterns in ai-development-guide.md
+4. If unable to resolve, ask user for clarification
+
+## File Organization
+
+**Tasks** (.agents/tasks/):
+- task-analysis.md: **Entry point**
+- work-planning.md: Create work plans
+- technical-design.md: Design documentation
+- acceptance-test-generation.md: Test skeleton generation
+- implementation.md: Implementation guidelines
+- quality-assurance.md: Quality standards
+
+**Workflows** (.agents/workflows/):
+- agentic-coding.md: Medium/Large scale workflow
+
+**Context Maps** (.agents/context-maps/):
+- task-rule-matrix.yaml: Task-to-rule mappings
+
+**Core Rules** (.agents/rules/core/):
+- metacognition.md: Self-assessment
+- ai-development-guide.md: Anti-patterns
+- documentation-criteria.md: Documentation criteria
+
+**Language Rules** (.agents/rules/language/):
+- rules.md: Development rules
+- testing.md: Testing standards
+
+**Contextual Rules** (.agents/rules/contextual/):
+- architecture/: Implementation approaches
+
+## Anti-Patterns to Avoid
+
+1. **Skipping task-analysis.md** → ALWAYS start with task analysis
+2. **Loading all rules upfront** → Load progressively based on task needs
+3. **Ignoring task entry/exit conditions** → Verify gates at each step
+4. **Working without task definitions** → Task definitions define WHAT to build
+6. **Assuming workflow is always needed** → Small tasks can use direct task definitions
+7. **Premature workflow selection** → Let task-analysis determine the approach
+
+## Success Metrics
+
+Track internally:
+- Task completion rate
+- Rules actually used vs loaded
+- Quality checks passing rate (should be 100%)
+- Appropriate path selection (direct vs workflow)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shinsuke Kagawa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,268 @@
+# Agentic Code
+
+Your AI (LLM), guided by built-in workflows. Describe what you want, and it follows a professional development process.
+
+[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![AGENTS.md](https://img.shields.io/badge/AGENTS.md-compliant-blue.svg)](https://agents.md)
+[![Version](https://img.shields.io/badge/version-0.5.1-blue.svg)](package.json)
+
+![Demo: Building a Slack bot with Agentic Code](.github/assets/demo.gif)
+
+*AI builds a Slack bot with tests & docs — in 30s*
+
+## What You Get
+
+```
+You: "Build a Slack bot with Gemini API"
+AI:  ✓ Reads AGENTS.md
+     ✓ Analyzes requirements
+     ✓ Plans architecture
+     ✓ Writes tests first
+     ✓ Implements with best practices
+     ✓ Verifies everything works
+```
+
+**Works out of the box—no configuration or learning curve required.**
+
+> **Using Claude Code with TypeScript?**  
+> Check out **[AI Coding Project Boilerplate](https://github.com/shinpr/ai-coding-project-boilerplate)** - a specialized alternative optimized for that specific stack.
+
+## Quick Start (30 seconds)
+
+```bash
+npx agentic-code my-project && cd my-project
+# Ready to go
+```
+
+That's it. Works with **any AI tool** - Codex, Cursor, Aider, or anything [AGENTS.md](https://agents.md) compatible.
+
+## Why This Exists
+
+Every AI coding tool has the same problems:
+- Forgets your project structure after 10 messages
+- Deletes tests when adding features
+- Ignores architectural decisions
+- Skips quality checks
+
+**We built the solution into the framework.** AGENTS.md guides your AI through professional workflows automatically.
+
+## What Makes It Different
+
+### 🎯 **Zero Configuration**
+Pre-built workflows that work without setup.
+
+### 🌐 **Universal Compatibility**
+Works with any programming language and any AI tool that reads AGENTS.md.
+
+### ✅ **Test-First by Default**
+Generates test skeletons before writing implementation code.
+
+### 📈 **Smart Scaling**
+- Simple task → Direct execution
+- Complex feature → Full workflow with approvals
+
+## How It Actually Works
+
+1. **AGENTS.md tells your AI the process** - Like a README but for AI agents
+2. **Progressive rule loading** - Only loads what's needed, when needed
+3. **Quality gates** - Automatic checkpoints ensure consistent output
+4. **You stay in control** - Approval points for major decisions
+
+```
+.agents/
+├── tasks/                   # What to build
+│   ├── task-analysis.md     # Entry point - AI starts here
+│   └── ...                  # Design, test, implement, QA tasks
+├── workflows/               # How to build it
+└── rules/                   # Quality standards
+```
+
+## Real Examples
+
+### Simple Task
+```bash
+You: "Add API endpoint for user search"
+# AI: Reads existing code → Plans changes → Tests → Implements → Done
+```
+
+### Complex Feature
+```bash
+You: "Build user authentication system"
+# AI: Requirements → Design doc → Your approval → Test skeletons →
+#     Implementation → Quality checks → Done
+```
+
+## Installation Options
+
+### For New Projects
+```bash
+# Create project
+npx agentic-code my-project
+
+# Optional: Add language-specific rules
+npx agentic-code my-project --lang=typescript
+```
+
+### For Existing Projects
+```bash
+# Copy the framework files
+cp -r path/to/agentic-code/AGENTS.md .
+cp -r path/to/agentic-code/.agents .
+
+# Set up language rules (choose one)
+cd .agents/rules/language
+ln -s general/rules.md rules.md
+ln -s general/testing.md testing.md
+```
+
+## Common Questions
+
+**Q: Can I use this with other AI coding tools besides Codex?**  
+Yes! This framework works with any AGENTS.md-compatible tool like Cursor, Aider, and other LLM-assisted development environments.
+
+**Q: What programming languages are supported?**  
+The framework is language-agnostic and works with any programming language through general development principles. For TypeScript projects, you can optionally use `--lang=typescript` to enable enhanced TypeScript-specific rules.
+
+**Q: Do I need to learn a new syntax?**  
+No. Describe what you want in plain language; the framework handles the rest.
+
+**Q: What if my AI doesn't support AGENTS.md?**  
+Check if your tool is [AGENTS.md compatible](https://agents.md). If so, point it to the AGENTS.md file first.
+
+**Q: Can I customize the workflows?**  
+Yes, everything in `.agents/` is customizable. The defaults are production-ready, but you can adapt them to your team's process.
+
+**Q: What about my existing codebase?**  
+It works with existing projects. Your AI analyzes the code and follows your established patterns.
+
+## The Technical Stuff
+
+The framework has three pillars:
+
+1. **Tasks** - Define WHAT to build
+2. **Workflows** - Define HOW to build it
+3. **Rules** - Define quality STANDARDS
+
+<details>
+<summary>Advanced features for the curious...</summary>
+
+### Progressive Rule Loading
+Rules load based on task analysis:
+- Small (1-2 files) → Direct execution with minimal rules
+- Medium/Large (3+ files) → Structured workflow with design docs
+- Each task definition specifies its required rules
+
+### Quality Gates
+Automatic checkpoints ensure:
+- Tests pass before proceeding
+- Code meets standards
+- Documentation stays updated
+
+### Special Features
+- **Metacognition** - AI self-assessment and error recovery
+- **Plan Injection** - Enforces all required steps are in work plan
+- **Test Generation** - Test skeletons from acceptance criteria
+- **1-Commit Principle** - Each task = one atomic commit
+
+</details>
+
+## Reviewing Generated Outputs
+
+**Important: Always review AI-generated outputs in a separate session.**
+
+LLMs cannot reliably review their own outputs within the same context. When the AI generates code or documents, it carries the same assumptions and blind spots into any "self-review." This leads to missed issues that a fresh perspective would catch.
+
+### Why Separate Sessions Matter
+
+| Same Session | New Session |
+|--------------|-------------|
+| Shares context and assumptions | Fresh perspective, no prior bias |
+| May overlook own mistakes | Catches issues objectively |
+| "Confirmation bias" in review | Applies standards independently |
+
+### How to Use Review Tasks
+
+After completing implementation or documentation, start a **new session** and request a review:
+
+```bash
+# For code review
+You: "Review the implementation in src/auth/ against docs/design/auth-design.md"
+# AI loads code-review task → Validates against Design Doc → Reports findings
+
+# For document review
+You: "Review docs/design/payment-design.md as a Design Doc"
+# AI loads technical-document-review task → Checks structure and content → Reports gaps
+
+# For test review
+You: "Review the integration tests in tests/integration/auth.test.ts"
+# AI loads integration-test-review task → Validates test quality → Reports issues
+```
+
+### Available Review Tasks
+
+| Task | Target | What It Checks |
+|------|--------|----------------|
+| `code-review` | Implementation files | Design Doc compliance, code quality, architecture |
+| `technical-document-review` | Design Docs, ADRs, PRDs | Structure, content quality, failure scenarios |
+| `integration-test-review` | Integration/E2E tests | Skeleton compliance, AAA structure, mock boundaries |
+
+**Pro tip:** Make reviews part of your workflow. After any significant generation, switch sessions and review before merging.
+
+### For Cursor Users: Isolated Context Reviews via MCP
+
+Cursor users can run reviews in isolated contexts without switching sessions using [`sub-agents-mcp`](https://github.com/shinpr/sub-agents-mcp). When review runs as a sub-agent, it executes in a completely separate context—achieving the same "fresh perspective" benefit as switching sessions, but without leaving your workflow.
+
+**Quick Setup:**
+
+Add to your MCP config (`~/.cursor/mcp.json` or `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "sub-agents": {
+      "command": "npx",
+      "args": ["-y", "sub-agents-mcp"],
+      "env": {
+        "AGENTS_DIR": "/absolute/path/to/your/project/.agents/tasks",
+        "AGENT_TYPE": "cursor"
+      }
+    }
+  }
+}
+```
+
+After restarting Cursor, task definitions become available as sub-agents:
+
+```bash
+You: "Use the code-review agent to review src/auth/ against docs/design/auth-design.md"
+```
+
+## Start Building
+
+```bash
+npx agentic-code my-awesome-project
+cd my-awesome-project
+# Tell your AI what to build
+```
+
+**Consistent, professional AI-assisted development.**
+
+---
+
+## Contributing
+
+Found a bug? Want to add language-specific rules? PRs welcome!
+
+- 🐛 [Report issues](https://github.com/shinpr/agentic-code/issues)
+- 🔧 [Submit PRs](https://github.com/shinpr/agentic-code/pulls)
+- 📚 [Improve docs](https://github.com/shinpr/agentic-code/pulls)
+
+## License
+
+MIT - Use it however you want.
+
+---
+
+Built on the [AGENTS.md standard](https://agents.md) — an open community specification for AI coding agents.
+
+**Ready to code properly with AI?** `npx agentic-code my-project`

package/bin/cli.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const projectName = args[0];
+const langOption = args.find(arg => arg.startsWith('--lang='));
+const selectedLang = langOption ? langOption.split('=')[1] : 'general';
+
+// Show help if no project name provided
+if (!projectName) {
+  console.log(`
+🤖 Agentic Code - Task-oriented context engineering framework
+
+Usage:
+  npx github:shinpr/agentic-code <project-name> [--lang=general|typescript]
+
+Examples:
+  npx github:shinpr/agentic-code my-project                    # General (language-agnostic)
+  npx github:shinpr/agentic-code my-project --lang=general     # General (explicit)
+  npx github:shinpr/agentic-code my-project --lang=typescript  # TypeScript-specific
+
+Language options:
+  general (default): Universal development principles for any language
+  typescript: Enhanced rules and TypeScript-specific tooling
+`);
+  process.exit(1);
+}
+
+// Validate project name
+if (!/^[a-zA-Z0-9_-]+$/.test(projectName)) {
+  console.error('❌ Project name can only contain letters, numbers, hyphens, and underscores.');
+  process.exit(1);
+}
+
+// Check if directory already exists
+if (fs.existsSync(projectName)) {
+  console.error(`❌ Directory '${projectName}' already exists.`);
+  process.exit(1);
+}
+
+console.log(`🚀 Creating Agentic Code project: ${projectName}`);
+console.log(`📝 Language: ${selectedLang}\n`);
+
+try {
+  // Create project directory
+  fs.mkdirSync(projectName, { recursive: true });
+
+  // Get the template directory (current package location)
+  const templateDir = path.dirname(__dirname);
+
+  // Copy template files
+  console.log('📁 Copying template files...');
+  copyDirectory(templateDir, projectName, ['.git', 'node_modules', 'bin']);
+
+  // Navigate to project directory
+  process.chdir(projectName);
+
+  // Initialize git repository
+  console.log('📦 Initializing Git repository...');
+  execSync('git init', { stdio: 'inherit' });
+
+  // Set up project configuration
+  console.log('⚙️  Setting up project configuration...');
+  execSync(`node scripts/setup.js --lang=${selectedLang}`, { stdio: 'inherit' });
+
+  // Create initial commit
+  console.log('💾 Creating initial commit...');
+  execSync('git add .', { stdio: 'inherit' });
+  execSync('git commit -m "feat: Initialize Agentic Code project"', { stdio: 'inherit' });
+
+  console.log(`\n🎉 Project '${projectName}' created successfully!`);
+  console.log('\n📚 Next steps:');
+  console.log(`   cd ${projectName}`);
+  console.log('   1. Read AGENTS.md to understand the framework');
+  console.log('   2. Start with: open .agents/tasks/task-analysis.md');
+  console.log('   3. Follow the task-rule-matrix for complex workflows');
+  console.log('\n💡 Need help? Check the documentation or open an issue on GitHub.');
+
+} catch (error) {
+  console.error('❌ Error creating project:', error.message);
+
+  // Cleanup on error
+  if (fs.existsSync(projectName)) {
+    try {
+      fs.rmSync(projectName, { recursive: true, force: true });
+    } catch (cleanupError) {
+      console.error('❌ Error during cleanup:', cleanupError.message);
+    }
+  }
+
+  process.exit(1);
+}
+
+// Helper function to copy directory recursively
+function copyDirectory(src, dest, excludeDirs = []) {
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (excludeDirs.includes(entry.name)) {
+      continue;
+    }
+
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      copyDirectory(srcPath, destPath, excludeDirs);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "agentic-code",
+  "version": "0.5.1",
+  "description": "Task-oriented context engineering framework for LLM coding agents - AGENTS.md standard compliant",
+  "files": [
+    "bin/",
+    ".agents/",
+    "AGENTS.md",
+    "scripts/"
+  ],
+  "bin": {
+    "agentic-code": "./bin/cli.js"
+  },
+  "scripts": {
+    "setup": "node scripts/setup.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "llm",
+    "ai",
+    "coding-agent",
+    "agents-md",
+    "context-engineering",
+    "agentic-coding",
+    "claude-code",
+    "cursor",
+    "github-copilot",
+    "template",
+    "boilerplate"
+  ],
+  "author": "Shinsuke Kagawa",
+  "license": "MIT",
+  "packageManager": "pnpm@10.15.1",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shinpr/agentic-code.git"
+  },
+  "bugs": {
+    "url": "https://github.com/shinpr/agentic-code/issues"
+  },
+  "homepage": "https://github.com/shinpr/agentic-code#readme",
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/scripts/setup.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Parse command line arguments for language option
+const args = process.argv.slice(2);
+const langOption = args.find(arg => arg.startsWith('--lang='));
+const selectedLang = langOption ? langOption.split('=')[1] : 'general';
+
+console.log('🚀 Setting up Agentic Code framework...\n');
+
+// Check if we're in a Git repository
+function isGitRepo() {
+  try {
+    execSync('git rev-parse --is-inside-work-tree', { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Initialize Git repository if not exists
+if (!isGitRepo()) {
+  console.log('📁 Initializing Git repository...');
+  try {
+    execSync('git init', { stdio: 'inherit' });
+    console.log('✓ Git repository initialized\n');
+  } catch (error) {
+    console.error('❌ Failed to initialize Git repository:', error.message);
+  }
+}
+
+// Set up language configuration
+const languageNames = {
+  general: 'General (language-agnostic)',
+  typescript: 'TypeScript'
+};
+
+const languageName = languageNames[selectedLang] || selectedLang;
+console.log(`⚙️  Setting up ${languageName} configuration...`);
+
+try {
+  const langPath = path.join(__dirname, '..', '.agents', 'rules', 'language');
+  const sourcePath = path.join(langPath, selectedLang);
+  const targetRulesPath = path.join(langPath, 'rules.md');
+  const targetTestingPath = path.join(langPath, 'testing.md');
+
+  // Check if source directory exists
+  if (!fs.existsSync(sourcePath)) {
+    console.error(`❌ Language '${selectedLang}' is not supported.`);
+    console.log('Available languages: general, typescript');
+    process.exit(1);
+  }
+
+  // Remove existing symlinks if they exist
+  if (fs.existsSync(targetRulesPath)) {
+    fs.unlinkSync(targetRulesPath);
+  }
+  if (fs.existsSync(targetTestingPath)) {
+    fs.unlinkSync(targetTestingPath);
+  }
+
+  // Create new symlinks
+  fs.symlinkSync(path.join(sourcePath, 'rules.md'), targetRulesPath);
+  fs.symlinkSync(path.join(sourcePath, 'testing.md'), targetTestingPath);
+
+  console.log(`✓ ${languageName} has been set as the active language.`);
+  console.log(`  - .agents/rules/language/rules.md → ${selectedLang}/rules.md`);
+  console.log(`  - .agents/rules/language/testing.md → ${selectedLang}/testing.md\n`);
+} catch (error) {
+  console.error('❌ Failed to setup language configuration:', error.message);
+}
+
+// Success message
+console.log('🎉 Agentic Code framework is ready to use!');
+console.log('\n📚 Quick Start:');
+console.log('   1. Read AGENTS.md to understand the framework');
+console.log('   2. Start with task analysis: .agents/tasks/task-analysis.md');
+console.log('   3. Follow the task-rule-matrix for complex workflows');
+console.log('\n💡 Need help? Check the documentation or open an issue on GitHub.');