# ITDA for GitHub Copilot

**Next-Generation Specification Driven Development**

This project uses **ITDA** (Next-Generation Specification Driven Development) configured for GitHub Copilot.

## Features

- 📋 **Constitutional Governance** - 9 immutable articles + Phase -1 Gates
- 📝 **EARS Requirements Format** - Unambiguous requirements with complete traceability
- 🧭 **Auto-Updating Project Memory** - Steering system maintains architecture, tech stack, and product context
- 🌐 **Bilingual Documentation** - All documents created in both English and Korean

## Custom Prompts

GitHub Copilot uses custom prompts in `.github/prompts/`:

```bash
# Generate project memory
#sdd-steering

# Create requirements
#sdd-requirements <feature>

# Design architecture
#sdd-design <feature>

# Break down into tasks
#sdd-tasks <feature>

# Implement feature
#sdd-implement <feature>

# Validate constitutional compliance
#sdd-validate <feature>
```

## Project Memory (Steering System)

**IMPORTANT**: Before starting any task, check if steering files exist in `steering/` directory:

- `steering/structure.md` - Architecture patterns, directory organization, naming conventions
- `steering/tech.md` - Technology stack, frameworks, development tools
- `steering/product.md` - Business context, product purpose, users

If these files exist, ALWAYS read them first to understand project context.

## SDD Workflow (8 Stages)

```
Research → Requirements → Design → Tasks → Implementation → Testing → Deployment → Monitoring
```

Each stage has:

- Quality gates
- Traceability requirements
- Constitutional validation

## EARS Requirements Format

All requirements must use EARS patterns:

```markdown
### Requirement: User Login

WHEN user provides valid credentials,
THEN the system SHALL authenticate the user
AND the system SHALL create a session.

#### Scenario: Successful login

- WHEN user enters correct email and password
- THEN system SHALL verify credentials
- AND system SHALL redirect to dashboard
```

## Constitutional Governance

ITDA enforces 9 immutable constitutional articles:

1. **Library-First Principle** - Features start as libraries
2. **CLI Interface Mandate** - All libraries expose CLI
3. **Test-First Imperative** - Tests before code (Red-Green-Blue)
4. **EARS Requirements Format** - Unambiguous requirements
5. **Traceability Mandate** - 100% coverage required
6. **Project Memory** - All prompts check steering first
7. **Simplicity Gate** - Maximum 3 projects initially
8. **Anti-Abstraction Gate** - Use framework features directly
9. **Integration-First Testing** - Real services over mocks

## Bilingual Documentation

**All agent-generated documents are created in both English and Korean.**

### Language Policy

- **English**: Reference/source documents (`.md`)
- **Korean**: Translations (`.ko.md`)
- **Prompts**: Always read English versions for work
- **Code References**: Requirement IDs, technical terms stay in English

## OpenHands-Inspired Modules (v3.0.0)

ITDA provides advanced AI agent assistance modules:

| Module                 | Purpose                       | Import                               |
| ---------------------- | ----------------------------- | ------------------------------------ |
| **StuckDetector**      | Detect agent stuck states     | `src/analyzers/stuck-detector.js`    |
| **MemoryCondenser**    | Compress session history      | `src/managers/memory-condenser.js`   |
| **AgentMemoryManager** | Extract & persist learnings   | `src/managers/agent-memory.js`       |
| **CriticSystem**       | Evaluate SDD stage quality    | `src/validators/critic-system.js`    |
| **SecurityAnalyzer**   | Detect security risks         | `src/analyzers/security-analyzer.js` |
| **IssueResolver**      | GitHub Issue analysis         | `src/resolvers/issue-resolver.js`    |
| **SkillLoader**        | Load keyword-triggered skills | `src/managers/skill-loader.js`       |
| **RepoSkillManager**   | Manage project skills         | `src/managers/repo-skill-manager.js` |

### Usage Example

```javascript
// Detect if agent is stuck
const { StuckDetector } = require('itda/src/analyzers/stuck-detector');
const detector = new StuckDetector();
detector.addEvent({ type: 'action', content: 'Read file' });
const analysis = detector.detect();

// Evaluate requirements quality
const { CriticSystem } = require('itda/src/validators/critic-system');
const critic = new CriticSystem();
const result = await critic.evaluate('requirements', context);
```

## Quick Start

### First Time Setup

1. Generate project memory:

   ```
   #sdd-steering
   ```

2. Review steering context in `steering/` directory

3. Start development

### Example Usage

```bash
# Greenfield Project (0→1)
#sdd-steering
#sdd-requirements user-authentication
#sdd-design user-authentication
#sdd-tasks user-authentication
#sdd-implement user-authentication

# Brownfield Project (1→n)
#sdd-steering
#sdd-change-init add-2fa
#sdd-change-apply add-2fa
```

## CLI Commands (v3.5.0)

ITDA provides powerful CLI tools that can be used from any terminal. Install with:

```bash
npm install -g itda-sdd
# or use directly
npx itda-sdd <command>
```

### Core Workflow Commands

| Command               | Purpose                        | Example                                  |
| --------------------- | ------------------------------ | ---------------------------------------- |
| `itda-workflow`     | Workflow state & metrics       | `npx itda-workflow status`             |
| `itda-requirements` | EARS requirements management   | `npx itda-requirements init <feature>` |
| `itda-design`       | C4 + ADR design documents      | `npx itda-design init <feature>`       |
| `itda-tasks`        | Task breakdown management      | `npx itda-tasks init <feature>`        |
| `itda-trace`        | Traceability analysis          | `npx itda-trace matrix`                |
| `itda-change`       | Change management (brownfield) | `npx itda-change init <change-id>`     |
| `itda-gaps`         | Gap detection & coverage       | `npx itda-gaps detect`                 |
| `itda-validate`     | Constitutional validation      | `npx itda-validate all`                |

### Supporting Commands

| Command          | Purpose                        | Example                         |
| ---------------- | ------------------------------ | ------------------------------- |
| `itda-init`    | Initialize ITDA in project   | `npx itda-init --copilot`     |
| `itda-share`   | Memory sharing across projects | `npx itda-share export`       |
| `itda-sync`    | Sync steering files            | `npx itda-sync`               |
| `itda-analyze` | Project analysis               | `npx itda-analyze complexity` |
| `itda-onboard` | AI platform onboarding         | `npx itda-onboard copilot`    |

### Advanced Commands (v3.5.0 NEW)

| Command              | Purpose                            | Example                                |
| -------------------- | ---------------------------------- | -------------------------------------- |
| `itda-orchestrate` | Multi-skill workflow orchestration | `npx itda-orchestrate auto <task>`   |
| `itda-browser`     | Browser automation & E2E testing   | `npx itda-browser run "click login"` |
| `itda-gui`         | Web GUI dashboard                  | `npx itda-gui start`                 |
| `itda-remember`    | Agent memory management            | `npx itda-remember extract`          |
| `itda-resolve`     | GitHub Issue auto-resolution       | `npx itda-resolve <issue-number>`    |
| `itda-convert`     | Format conversion (Spec Kit)       | `npx itda-convert to-speckit`        |

### Replanning Commands (v3.6.0 NEW)

| Command                               | Purpose                      | Example                                                      |
| ------------------------------------- | ---------------------------- | ------------------------------------------------------------ |
| `itda-orchestrate replan`           | Execute dynamic replanning   | `npx itda-orchestrate replan <context-id>`                 |
| `itda-orchestrate goal register`    | Register a new goal          | `npx itda-orchestrate goal register --name "Deploy API"`   |
| `itda-orchestrate goal update`      | Update goal progress         | `npx itda-orchestrate goal update <goal-id> --progress 50` |
| `itda-orchestrate goal status`      | View goal status             | `npx itda-orchestrate goal status [goal-id]`               |
| `itda-orchestrate optimize run`     | Run path optimization        | `npx itda-orchestrate optimize run <path-id>`              |
| `itda-orchestrate optimize suggest` | Get optimization suggestions | `npx itda-orchestrate optimize suggest <path-id>`          |
| `itda-orchestrate path analyze`     | Analyze execution path       | `npx itda-orchestrate path analyze <path-id>`              |
| `itda-orchestrate path optimize`    | Optimize execution path      | `npx itda-orchestrate path optimize <path-id>`             |

### Guardrails Commands (v3.9.0 NEW)

| Command                                    | Purpose                           | Example                                                          |
| ------------------------------------------ | --------------------------------- | ---------------------------------------------------------------- |
| `itda-validate guardrails`               | Input/Output guardrail validation | `npx itda-validate guardrails --type input`                    |
| `itda-validate guardrails --type output` | Output content validation         | `echo "content" \| npx itda-validate guardrails --type output` |
| `itda-validate guardrails --type safety` | Safety check with constitutional  | `npx itda-validate guardrails --type safety --constitutional`  |
| `itda-validate guardrails-chain`         | Chain multiple guardrails         | `npx itda-validate guardrails-chain --parallel`                |

## Enterprise Scale Modules (v5.5.0 NEW)

ITDA v5.5.0 adds advanced modules for analyzing enterprise-scale projects (10,000+ files):

| Module                     | Purpose                              | Import                                       |
| -------------------------- | ------------------------------------ | -------------------------------------------- |
| **LargeProjectAnalyzer**   | Streaming analysis for 100K+ files   | `src/analyzers/large-project-analyzer.js`    |
| **ComplexityAnalyzer**     | Cyclomatic & cognitive complexity    | `src/analyzers/complexity-analyzer.js`       |
| **RustMigrationGenerator** | C/C++ to Rust migration analysis     | `src/generators/rust-migration-generator.js` |
| **CodeGraphMCP**           | MCP-based code intelligence server   | `src/integrations/code-graph-mcp.js`         |
| **HierarchicalReporter**   | Drilldown reports for large projects | `src/reporters/hierarchical-reporter.js`     |

### Usage Examples

```javascript
// Analyze large projects (100,000+ files)
const { LargeProjectAnalyzer } = require('itda-sdd');
const analyzer = new LargeProjectAnalyzer('/path/to/project');
const result = await analyzer.analyze();
console.log(result.stats.totalFiles);

// Calculate code complexity
const { ComplexityAnalyzer } = require('itda-sdd');
const complexity = new ComplexityAnalyzer();
const score = complexity.calculateCyclomaticComplexity(code, 'javascript');

// Analyze C/C++ for Rust migration
const { RustMigrationGenerator } = require('itda-sdd');
const generator = new RustMigrationGenerator('/path/to/cpp-project');
const analysis = await generator.analyze();
```

### CLI + Prompt Integration

Combine CLI commands with GitHub Copilot prompts for maximum efficiency:

```bash
# Initialize workflow, then use prompt
npx itda-workflow init user-auth
#sdd-requirements user-auth

# Analyze issues, then resolve
npx itda-resolve analyze 42
#sdd-implement issue-42-fix

# Start GUI dashboard for visual tracking
npx itda-gui start
```

## Learn More

- [ITDA Documentation](https://github.com/gaebalai/itda-sdd)
- [CLI Reference](https://github.com/gaebalai/itda-sdd#cli-commands) - Detailed CLI options
- [Constitutional Governance](steering/rules/constitution.md)
- [8-Stage SDD Workflow](steering/rules/workflow.md)

**Tip**: Run `npx itda-sdd --help` for complete CLI documentation.

---

**ITDA for GitHub Copilot** - 잇다 - Bringing specifications, design, and code together.