agentic-code 0.5.1 → 0.6.0

package/README.md

@@ -74,7 +74,7 @@ Generates test skeletons before writing implementation code.
 │   ├── task-analysis.md     # Entry point - AI starts here
 │   └── ...                  # Design, test, implement, QA tasks
 ├── workflows/               # How to build it
-└── rules/                   # Quality standards
+└── skills/                  # Quality standards (Codex-compatible)
 ```
 
 ## Real Examples
@@ -96,11 +96,7 @@ You: "Build user authentication system"
 
 ### 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
@@ -108,11 +104,17 @@ npx agentic-code my-project --lang=typescript
 # Copy the framework files
 cp -r path/to/agentic-code/AGENTS.md .
 cp -r path/to/agentic-code/.agents .
+```
+
+### Skills
 
-# Set up language rules (choose one)
-cd .agents/rules/language
-ln -s general/rules.md rules.md
-ln -s general/testing.md testing.md
+`.agents/skills/` contains reusable skill files in the [Codex Skills format](https://github.com/openai/codex/blob/main/docs/skills.md). Each skill has a `SKILL.md` with instructions that AI agents can discover and apply.
+
+**Codex**: You can install skills globally so Codex picks them up across all projects:
+
+```bash
+npx agentic-code-install-skills --codex
+# Installs to ~/.codex/skills/agentic-code/
 ```
 
 ## Common Questions
@@ -120,8 +122,8 @@ ln -s general/testing.md testing.md
 **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: What programming languages are supported?**
+The framework is language-agnostic and works with any programming language through general development principles. TypeScript-specific rules are available in `skills/*/references/typescript.md`.
 
 **Q: Do I need to learn a new syntax?**  
 No. Describe what you want in plain language; the framework handles the rest.
@@ -141,16 +143,16 @@ The framework has three pillars:
 
 1. **Tasks** - Define WHAT to build
 2. **Workflows** - Define HOW to build it
-3. **Rules** - Define quality STANDARDS
+3. **Skills** - 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
+### Progressive Skill Loading
+Skills load based on task analysis:
+- Small (1-2 files) → Direct execution with minimal skills
 - Medium/Large (3+ files) → Structured workflow with design docs
-- Each task definition specifies its required rules
+- Each task definition specifies its required skills
 
 ### Quality Gates
 Automatic checkpoints ensure:

package/bin/cli.js

@@ -7,8 +7,6 @@ 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) {
@@ -16,16 +14,12 @@ if (!projectName) {
 🤖 Agentic Code - Task-oriented context engineering framework
 
 Usage:
-  npx github:shinpr/agentic-code <project-name> [--lang=general|typescript]
+  npx github:shinpr/agentic-code <project-name>
 
 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
+  npx github:shinpr/agentic-code my-project
 
-Language options:
-  general (default): Universal development principles for any language
-  typescript: Enhanced rules and TypeScript-specific tooling
+Skills include language-specific references (e.g., .agents/skills/coding-rules/references/typescript.md)
 `);
   process.exit(1);
 }
@@ -42,8 +36,7 @@ if (fs.existsSync(projectName)) {
   process.exit(1);
 }
 
-console.log(`🚀 Creating Agentic Code project: ${projectName}`);
-console.log(`📝 Language: ${selectedLang}\n`);
+console.log(`🚀 Creating Agentic Code project: ${projectName}\n`);
 
 try {
   // Create project directory
@@ -63,10 +56,6 @@ try {
   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' });
@@ -77,7 +66,7 @@ try {
   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('   3. Skills are in .agents/skills/');
   console.log('\n💡 Need help? Check the documentation or open an issue on GitHub.');
 
 } catch (error) {
@@ -114,4 +103,4 @@ function copyDirectory(src, dest, excludeDirs = []) {
       fs.copyFileSync(srcPath, destPath);
     }
   }
-}
+}

package/bin/install-codex-skills.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+
+// Target configurations
+const TARGETS = {
+  codex: {
+    dir: path.join(os.homedir(), '.codex', 'skills'),
+    name: 'agentic-code',
+    description: 'OpenAI Codex CLI',
+    postInstall: 'Restart Codex to load the skills.\nNote: Enable skills with --enable skills flag or in config.toml'
+  }
+  // Future targets can be added here
+};
+
+// Show help
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`
+Usage: agentic-code-install-skills [options]
+
+Options:
+  --codex    Install skills to ~/.codex/skills/.agentic-code (default)
+  --help     Show this help message
+
+Examples:
+  agentic-code-install-skills           # Install to Codex (default)
+  agentic-code-install-skills --codex   # Install to Codex (explicit)
+`);
+  process.exit(0);
+}
+
+// Determine target (default: codex)
+let targetKey = 'codex';
+if (args.includes('--codex')) {
+  targetKey = 'codex';
+}
+
+const target = TARGETS[targetKey];
+if (!target) {
+  console.error(`Error: Unknown target '${targetKey}'`);
+  process.exit(1);
+}
+
+// Get source directory (from installed package or local)
+function getSourceSkillsDir() {
+  // When run from npx or installed globally
+  const packageSkillsDir = path.join(__dirname, '..', '.agents', 'skills');
+  if (fs.existsSync(packageSkillsDir)) {
+    return packageSkillsDir;
+  }
+
+  // When run from project directory
+  const localSkillsDir = path.join(process.cwd(), '.agents', 'skills');
+  if (fs.existsSync(localSkillsDir)) {
+    return localSkillsDir;
+  }
+
+  return null;
+}
+
+// Copy directory recursively
+function copyDirectory(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDirectory(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+// Main
+function main() {
+  const sourceDir = getSourceSkillsDir();
+
+  if (!sourceDir) {
+    console.error('Error: .agents/skills directory not found.');
+    process.exit(1);
+  }
+
+  const targetDir = path.join(target.dir, target.name);
+
+  console.log(`Installing Agentic Code skills to ${target.description}...\n`);
+  console.log(`Source: ${sourceDir}`);
+  console.log(`Target: ${targetDir}\n`);
+
+  // Create target parent directory if not exists
+  if (!fs.existsSync(target.dir)) {
+    fs.mkdirSync(target.dir, { recursive: true });
+    console.log(`Created: ${target.dir}`);
+  }
+
+  // Remove existing target directory
+  if (fs.existsSync(targetDir)) {
+    fs.rmSync(targetDir, { recursive: true, force: true });
+    console.log(`Removed existing: ${targetDir}`);
+  }
+
+  // Copy skills
+  copyDirectory(sourceDir, targetDir);
+
+  // List installed skills
+  const skills = fs.readdirSync(targetDir, { withFileTypes: true })
+    .filter(entry => entry.isDirectory())
+    .map(entry => entry.name);
+
+  console.log(`\nInstalled ${skills.length} skills:`);
+  skills.forEach(skill => console.log(`  - ${skill}`));
+
+  console.log('\nDone.');
+  if (target.postInstall) {
+    console.log(target.postInstall);
+  }
+}
+
+main();

package/package.json

@@ -1,32 +1,29 @@
 {
   "name": "agentic-code",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Task-oriented context engineering framework for LLM coding agents - AGENTS.md standard compliant",
   "files": [
     "bin/",
     ".agents/",
-    "AGENTS.md",
-    "scripts/"
+    "AGENTS.md"
   ],
   "bin": {
-    "agentic-code": "./bin/cli.js"
+    "agentic-code": "./bin/cli.js",
+    "agentic-code-install-skills": "./bin/install-codex-skills.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",
+    "coding-agent",
+    "llm",
+    "codex",
     "cursor",
-    "github-copilot",
-    "template",
-    "boilerplate"
+    "windsurf",
+    "cline"
   ],
   "author": "Shinsuke Kagawa",
   "license": "MIT",

package/.agents/rules/language/typescript/testing.md

@@ -1,284 +0,0 @@
-# TypeScript Testing Rules
-
-## Test Framework
-- **Vitest**: This project uses Vitest
-- Test imports: `import { describe, it, expect, beforeEach, vi } from 'vitest'`
-- Mock creation: Use `vi.mock()`
-
-## Basic Testing Policy
-
-### Quality Requirements
-- **Coverage**: Unit test coverage must be 80% or higher
-- **Independence**: Each test can run independently
-- **Reproducibility**: Tests are environment-independent
-
-### Coverage Requirements
-**Mandatory**: Unit test coverage must be 80% or higher
-**Metrics**: Statements, Branches, Functions, Lines
-
-### Test Types and Scope
-1. **Unit Tests**
-   - Verify behavior of individual functions or classes
-   - Mock all external dependencies
-
-2. **Integration Tests**
-   - Verify coordination between multiple components
-   - Use actual dependencies (DB, API, etc.)
-
-3. **E2E Cross-functional Tests** [MANDATORY for new features]
-   - Test existing features remain stable after new feature integration
-   - Coverage based on Design Doc's Integration Point Map impact levels
-   - Verify performance degradation stays within project-defined limits
-
-### TypeScript/Vitest Pattern Reference
-
-```typescript
-describe('Cross-functional E2E Tests', () => {
-  // Pattern 1: Baseline → Change → Verify
-  it('should maintain existing behavior after new feature', async () => {
-    // 1. Capture baseline
-    const baseline = await testExistingFeature()
-
-    // 2. Enable new feature
-    await enableNewFeature()
-
-    // 3. Verify continuity
-    const result = await testExistingFeature()
-    expect(result).toEqual(baseline)
-    expect(result.responseTime).toBeLessThan(
-      baseline.responseTime * 1.2 // Project-specific threshold
-    )
-  })
-
-  // Pattern 2: Data integrity across features
-  it('should preserve data integrity', async () => {
-    const data = await createTestData()
-    await newFeatureOperation(data.id)
-
-    const retrieved = await existingFeatureGet(data.id)
-    expect(retrieved).toEqual(data) // No unexpected mutations
-  })
-})
-
-**Note**: LLM outputs naturally vary - test behavior, not exact matches
-
-## TDD Process [MANDATORY for all code changes]
-
-**Execute this process for every code change:**
-
-### RED Phase
-1. Write test that defines expected behavior
-2. Run test
-3. Confirm test FAILS (if it passes, the test is wrong)
-
-### GREEN Phase
-1. Write MINIMAL code to make test pass
-2. Run test
-3. Confirm test PASSES
-
-### REFACTOR Phase
-1. Improve code quality
-2. Run test
-3. Confirm test STILL PASSES
-
-### VERIFY Phase [MANDATORY - 0 ERRORS REQUIRED]
-1. Execute ALL quality check commands below
-2. Fix any errors until ALL commands pass with 0 errors
-3. Confirm no regressions
-4. ENFORCEMENT: Cannot proceed with ANY errors or warnings
-
-**Exceptions (TDD not required):**
-
-The following cases do NOT require test-first approach:
-
-1. **Pure Configuration Files**
-   - package.json, tsconfig.json, build configs
-   - Environment variable files (.env templates)
-   - Linter/formatter configurations
-   - Rationale: No business logic to verify
-
-2. **Documentation Only Changes**
-   - README updates
-   - Code comments additions
-   - Markdown documentation
-   - Rationale: No executable behavior to test
-
-3. **Emergency Hotfixes**
-   - Production incidents requiring immediate fix
-   - Security vulnerabilities requiring urgent patch
-   - **REQUIREMENT**: Add tests immediately after deploying fix
-   - Rationale: Speed prioritized in crisis, but tests must follow
-
-4. **Exploratory Spikes**
-   - Time-boxed research (max 2-4 hours)
-   - Proof-of-concept for uncertain technology
-   - **REQUIREMENT**: Discard spike code or rewrite with tests before merging
-   - Rationale: Learning phase, not production code
-
-5. **Build/Deployment Scripts**
-   - CI/CD pipeline definitions
-   - Deployment automation scripts
-   - **NOTE**: Complex scripts with business logic DO require tests
-   - Rationale: Verified through actual deployment, not unit tests
-
-**When in Doubt**: Default to TDD. Exceptions are narrow, not broad.
-
-## Test Design Principles
-
-### Test Case Structure
-- Tests consist of three stages: "Arrange," "Act," "Assert"
-- Clear naming that shows purpose of each test
-- One test case verifies only one behavior
-
-### Test Data Management
-- Manage test data in dedicated directories
-- Define test-specific environment variable values
-- Always mock sensitive information
-- Keep test data minimal, using only data directly related to test case verification purposes
-
-### Mock and Stub Usage Policy
-
-✅ **Recommended: Mock external dependencies in unit tests**
-- Merit: Ensures test independence and reproducibility
-- Practice: Mock DB, API, file system, and other external dependencies
-
-❌ **Avoid: Actual external connections in unit tests**
-- Reason: Slows test speed and causes environment-dependent problems
-
-### Test Failure Response Decision Criteria
-
-**Fix tests**: Wrong expected values, references to non-existent features, dependence on implementation details, implementation only for tests
-**Fix implementation**: Valid specifications, business logic, important edge cases
-**When in doubt**: Confirm with user
-
-## Test Helper Utilization Rules
-
-### Basic Principles
-Test helpers are utilized to reduce duplication in test code and improve maintainability.
-
-### Decision Criteria
-| Mock Characteristics | Response Policy |
-|---------------------|-----------------|
-| **Simple and stable** | Consolidate in common helpers |
-| **Complex or frequently changing** | Individual implementation |
-| **Duplicated in 3+ places** | Consider consolidation |
-| **Test-specific logic** | Individual implementation |
-
-### Test Helper Usage Examples
-```typescript
-// ✅ Recommended: Utilize builder pattern
-const testData = new TestDataBuilder()
-  .withDefaults()
-  .withName('Test User')
-  .build()
-
-// ✅ Recommended: Custom assertions
-function assertValidUser(user: unknown): asserts user is User {
-  // Validation logic
-}
-
-// ❌ Avoid: Individual implementation of duplicate complex mocks
-```
-
-## Test Implementation Conventions
-
-### Directory Structure
-**File structure:**
-- src/application/services/service.ts: Main service file
-- src/application/services/__tests__/service.test.ts: Unit tests
-- src/application/services/__tests__/service.int.test.ts: Integration tests
-
-### Naming Conventions
-- Test files: `{target-file-name}.test.ts`
-- Integration test files: `{target-file-name}.int.test.ts`
-- Test suites: Names describing target features or situations
-- Test cases: Names describing expected behavior
-
-
-### Test Code Quality Rules
-
-✅ **Recommended: Keep all tests always active**
-- Merit: Guarantees test suite completeness
-- Practice: Fix problematic tests and activate them
-
-❌ **Avoid: test.skip() or commenting out**
-- Reason: Creates test gaps and incomplete quality checks
-- Solution: Completely delete unnecessary tests
-
-## Test Quality Criteria [MANDATORY]
-
-1. **Boundary coverage**: Include empty/zero/max/error cases with happy paths
-2. **Literal expectations**: `expect(calc(100)).toBe(10)` — use literals, not `100 * RATE`
-3. **Result verification**: Assert return values and state, not call order
-4. **Meaningful assertions**: Every test must have at least one `expect()`
-5. **Mock external I/O only**: Mock DB/API/filesystem, use real internal utils
-
-## Test Granularity Principles
-
-### Core Principle: Observable Behavior Only
-**MUST Test**: Public APIs, return values, exceptions, external calls, persisted state
-**MUST NOT Test**: Private methods, internal state, algorithm implementation details
-
-```typescript
-// ✅ Test observable behavior
-expect(calculatePrice(100, 0.1)).toBe(110)
-
-// ❌ Test implementation details
-expect((calculator as any).taxRate).toBe(0.1)
-```
-
-## Mock Type Safety Enforcement
-
-### Minimal Type Definition Requirements
-```typescript
-// ✅ Only required parts
-type TestRepo = Pick<Repository, 'find' | 'save'>
-const mock: TestRepo = { find: vi.fn(), save: vi.fn() }
-
-// Only when absolutely necessary, with clear justification
-const sdkMock = {
-  call: vi.fn()
-} as unknown as ExternalSDK // Complex external SDK type structure
-```
-
-## Basic Vitest Example
-
-```typescript
-import { describe, it, expect, beforeEach, vi } from 'vitest'
-
-// Mock setup example
-vi.mock('./userService', () => ({
-  getUserById: vi.fn(),
-  updateUser: vi.fn()
-}))
-
-describe('ComponentName', () => {
-  it('should follow AAA pattern', () => {
-    // Arrange
-    const input = 'test'
-
-    // Act
-    const result = someFunction(input)
-
-    // Assert
-    expect(result).toBe('expected')
-  })
-})
-```
-
-## Quality Check Commands [MANDATORY for VERIFY phase]
-
-**ALL TypeScript/JavaScript commands MUST pass with 0 errors before task completion:**
-
-```bash
-npm test              # MUST pass all tests
-npm run build        # MUST build successfully
-npm run lint         # MUST have 0 lint errors
-npm run type-check   # MUST have 0 type errors
-```
-
-**ENFORCEMENT:**
-- Run ALL applicable commands listed above
-- Fix ANY errors or warnings before marking task complete
-- If command doesn't exist in package.json, skip that specific command
-- Document which commands were run in task completion

package/scripts/setup.js

@@ -1,82 +0,0 @@
-#!/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.');