# 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` |

## 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. Install with:

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

### Core Commands

| Command               | Purpose                   | Example                                  |
| --------------------- | ------------------------- | ---------------------------------------- |
| `itda-workflow`     | Workflow state & metrics  | `npx itda-workflow status`             |
| `itda-requirements` | EARS requirements         | `npx itda-requirements init <feature>` |
| `itda-design`       | C4 + ADR design           | `npx itda-design init <feature>`       |
| `itda-tasks`        | Task breakdown            | `npx itda-tasks init <feature>`        |
| `itda-trace`        | Traceability              | `npx itda-trace matrix`                |
| `itda-validate`     | Constitutional validation | `npx itda-validate all`                |

### Advanced Commands (v3.5.0 NEW)

| Command              | Purpose                   | Example                                |
| -------------------- | ------------------------- | -------------------------------------- |
| `itda-orchestrate` | Multi-skill orchestration | `npx itda-orchestrate auto <task>`   |
| `itda-browser`     | Browser automation & E2E  | `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 resolution   | `npx itda-resolve <issue-number>`    |
| `itda-convert`     | Format conversion         | `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();
```

## 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 Windsurf** - 잇다 - Bringing specifications, design, and code together.