@jadeit/forge-ai 0.0.0 → 1.2.1

package/commands/forge-3-build-6-review.md

@@ -0,0 +1,50 @@
+---
+description: Forge Feature Dev - Sub-phase 6 Review
+agent: forge-build
+---
+
+# Forge AI: Phase 3 - Sub-phase 6: Review
+
+Invoke the `@forge-review` subagent for Feature Dev sub-phase 6.
+
+## Purpose
+
+Quality review using automated checks followed by AI code review.
+
+## Quality Gates
+
+Run these automated checks:
+1. **Lint Check** - Code style
+2. **Type Check** - Type safety
+3. **Security Audit** - Vulnerabilities
+4. **Tests** - All must pass
+5. **Coverage** - Must meet threshold (default 80%)
+
+## AI Code Review
+
+After automated checks pass, review for:
+- SOLID principles compliance
+- Design pattern usage
+- Error handling
+- Security
+- Performance
+- Maintainability
+
+## Issue Severity
+
+| Severity | Action |
+|----------|--------|
+| Critical | Must fix before proceeding |
+| High | Should fix |
+| Medium | Consider fixing |
+| Low | Nice to have |
+
+## Rework Decision
+
+- **Minor issues** → Loop to `/forge-3-build-5-implement`
+- **Approach issues** → Loop to `/forge-3-build-4-approach`
+
+## Next Steps
+
+After review passes, proceed to:
+- `/forge-3-build-7-validate`

package/commands/forge-3-build-7-validate.md

@@ -0,0 +1,49 @@
+---
+description: Forge Feature Dev - Sub-phase 7 Validate
+agent: forge-build
+---
+
+# Forge AI: Phase 3 - Sub-phase 7: Validate
+
+Invoke the `@forge-validate` subagent for Feature Dev sub-phase 7.
+
+## Purpose
+
+Validate tests against the task document's acceptance criteria.
+
+## Validation Checklist
+
+### 1. Coverage Mapping
+For each acceptance criterion, identify which test(s) validate it.
+
+| Acceptance Criterion | Test(s) | Covered |
+|---------------------|---------|---------|
+| AC1: Users can authenticate | auth.test.ts | ✓ |
+| AC2: Session expires | - | ✗ |
+
+### 2. Assertion Quality
+- Meaningful assertions (not just "no error")
+- Appropriate mocking
+- Error path testing
+
+### 3. Negative Testing
+- Invalid input handling
+- Edge cases
+- Error scenarios
+
+### 4. Independence Check
+Would tests fail if implementation removed?
+
+## Validation Thresholds
+
+From `.forge/config.yaml`:
+- Test coverage minimum: 80% (configurable)
+
+## Rework Decision
+
+If validation fails → Loop to `/forge-3-build-5-implement` for test fixes
+
+## Next Steps
+
+After validation passes, proceed to:
+- `/forge-3-build-8-summarise`

package/commands/forge-3-build-8-summarise.md

@@ -0,0 +1,49 @@
+---
+description: Forge Feature Dev - Sub-phase 8 Summarise
+agent: forge-build
+---
+
+# Forge AI: Phase 3 - Sub-phase 8: Summarise
+
+Invoke the `@forge-summarise` subagent for Feature Dev sub-phase 8.
+
+## Purpose
+
+Document what was accomplished.
+
+## Summary Content
+
+### Document in task document:
+
+1. **What Was Built** - Brief description
+2. **Changes Made** - Table of files modified
+3. **Decisions Made** - Any deviations from approach
+4. **Known Limitations** - Deferred items, technical debt
+5. **Next Steps** - What comes next
+
+### Update task document frontmatter:
+```yaml
+status: complete
+completed: [timestamp]
+```
+
+### Update state file:
+```yaml
+features:
+  task-slug:
+    status: complete
+```
+
+## Lifecycle Complete
+
+Feature Development Lifecycle is complete when:
+- ✓ All 8 sub-phases completed
+- ✓ Task document updated with summary
+- ✓ State file updated
+
+## Next Actions
+
+After lifecycle complete:
+1. Run full test suite
+2. Manual testing
+3. Next feature or Phase 4: Testing

package/commands/forge-3-build.md

@@ -0,0 +1,54 @@
+---
+description: Forge AI Phase 3 - Development via Feature Dev lifecycle
+agent: forge-build
+---
+
+# Forge AI: Phase 3 - Development
+
+Invoke the `@forge-build` agent to begin Feature Development.
+
+## Feature Dev Lifecycle
+
+| Sub-Phase | Command | Description |
+|-----------|---------|-------------|
+| 1 | `/forge-3-build-1-discover` | Understand what needs to be built |
+| 2 | `/forge-3-build-2-explore` | Explore relevant existing code |
+| 3 | `/forge-3-build-3-clarify` | Resolve ambiguities |
+| 4 | `/forge-3-build-4-approach` | Design/validate approach |
+| 5 | `/forge-3-build-5-implement` | Build the feature |
+| 6 | `/forge-3-build-6-review` | Quality review |
+| 7 | `/forge-3-build-7-validate` | Test validation |
+| 8 | `/forge-3-build-8-summarise` | Document accomplishments |
+
+## Usage
+
+Run `/forge-3-build` for full lifecycle, or use specific sub-phase commands:
+- `/forge-3-build-1-discover`
+- `/forge-3-build-2-explore`
+- `/forge-3-build-3-clarify`
+- `/forge-3-build-4-approach`
+- `/forge-3-build-5-implement`
+- `/forge-3-build-6-review`
+- `/forge-3-build-7-validate`
+- `/forge-3-build-8-summarise`
+
+## Operating Modes
+
+| Mode | Condition | Behaviour |
+|------|-----------|-----------|
+| Brownfield | Task document exists with detail | Lighter discovery, validate approach |
+| Greenfield | No task document | Full scoping, create task doc |
+
+## Flags
+
+- `--only {sub-phase}` - Run specific sub-phase
+- `--task {slug}` - Work on specific task
+- `--model {tier}` - Override model tier
+
+## Prerequisites
+
+Phase 2 must be complete. Check `.forge/state.yaml`.
+
+## Next Steps
+
+After Phase 3 complete, use `/forge-4-test` for Phase 4: Testing.

package/commands/forge-4-test.md

@@ -0,0 +1,45 @@
+---
+description: Forge AI Phase 4 - Functional testing and UAT
+agent: forge-test
+---
+
+# Forge AI: Phase 4 - Testing
+
+Invoke the `@forge-test` agent to begin User Acceptance Testing.
+
+## What Happens
+
+1. User stories and acceptance criteria are loaded
+2. UAT checklist is presented
+3. For each item, you confirm: passed / failed / skipped
+4. Failed items → defect reports created in `docs/defects/`
+5. Results → `docs/testing/uat-results.md`
+6. State updated after your sign-off
+
+## UAT Gate Process
+
+1. Present checklist of user stories with acceptance criteria
+2. You verify each by running the project locally
+3. For each item: PASSED / FAILED / SKIPPED
+4. Failed items produce defect reports
+5. Skipped items logged with reason
+6. Phase 5 proceeds only after your sign-off
+
+## Requirements
+
+User acceptance testing MUST be done by:
+- Running the project locally
+- Validating each user story against implementation
+- NOT just running automated tests
+
+## Defect Handling
+
+For failed items:
+1. Create defect report in `docs/defects/`
+2. Document reproduction steps
+3. Classify: design or implementation
+4. Route to appropriate phase
+
+## Next Steps
+
+After Phase 4 complete, use `/forge-5-deploy` for Phase 5: Deployment.

package/commands/forge-5-deploy.md

@@ -0,0 +1,50 @@
+---
+description: Forge AI Phase 5 - Deployment
+agent: forge-deploy
+---
+
+# Forge AI: Phase 5 - Deployment
+
+Invoke the `@forge-deploy` agent to execute deployment.
+
+## What Happens
+
+1. Deployment documentation is loaded from `docs/deployment/`
+2. Infrastructure task documents reviewed
+3. Deployment steps executed
+4. Verification of deployment success
+5. Post-deployment monitoring confirmed
+6. State updated
+
+## Pre-Deployment Checklist
+
+- [ ] All tests pass in staging
+- [ ] Environment variables configured
+- [ ] Database migrations ready
+- [ ] Secrets configured
+- [ ] Monitoring/alerting configured
+- [ ] Rollback plan documented
+
+## Deployment Targets
+
+- Development: `npm run dev`
+- Staging: `npm run deploy:staging`
+- Production: `npm run deploy:production`
+
+## Verification
+
+After deployment:
+- Health endpoint check
+- Version verification
+- Critical feature smoke test
+
+## Rollback
+
+If deployment fails:
+1. Identify issue
+2. Execute rollback procedure
+3. Verify recovery
+
+## Next Steps
+
+After Phase 5 complete, use `/forge-6-maintain` for Phase 6: Maintenance.

package/commands/forge-6-maintain.md

@@ -0,0 +1,66 @@
+---
+description: Forge AI Phase 6 - Maintenance triage, routing, and audit
+agent: forge-maintain
+---
+
+# Forge AI: Phase 6 - Maintenance
+
+Invoke the `@forge-maintain` agent for maintenance operations.
+
+## Important Note
+
+**No new code is written in Phase 6.** Issues are routed to appropriate phases for resolution.
+
+## Maintenance Operations
+
+### 1. Triage
+
+Take an incident, error, or observation and produce a structured defect report in `docs/defects/`.
+
+**Input Sources:**
+- Error logs
+- APM alerts (Sentry, DataDog)
+- User reports
+- Test failures
+- UAT findings
+
+### 2. Route
+
+Based on classification:
+
+| Classification | Route To | Mode |
+|----------------|----------|------|
+| Design flaw | `/forge-2-design` | Brownfield |
+| Implementation bug | `/forge-3-build` | Greenfield |
+| Configuration issue | `/forge-5-deploy` | - |
+
+### 3. Audit
+
+Scan existing defect reports and summarise status:
+- Open defects
+- Routed defects
+- Resolved defects
+
+## Severity Levels
+
+| Severity | Criteria | Response Time |
+|----------|----------|---------------|
+| Critical | System down, data loss | Immediate |
+| High | Major feature broken | 24 hours |
+| Medium | Feature broken, workaround | 1 week |
+| Low | Minor issue | Next sprint |
+
+## Defect Routing
+
+When you encounter an issue:
+
+1. Investigate and gather information
+2. Create defect report with severity and classification
+3. Propose routing based on classification
+4. You confirm before routing
+
+## Commands
+
+- `/forge-maintain-audit` - Run defect audit
+- `/forge-maintain-triage` - Triage new issue
+- `/forge-maintain-route` - Route existing defect

package/commands/forge-init.md

@@ -0,0 +1,111 @@
+---
+description: Forge AI - Initialize Forge in a new project
+agent: forge-orchestrator
+---
+
+# Forge Init - Bootstrap Command
+
+Initialize Forge AI in a new project directory.
+
+## Usage
+
+`/forge-init`
+
+## What It Does
+
+### 1. Create Directory Structure
+
+Creates:
+```
+.forge/
+├── config.yaml
+├── state.yaml
+├── adapters/opencode/
+│   ├── agents/
+│   ├── commands/
+│   └── skills/
+└── templates/
+    ├── planning/
+    ├── design/tasks/
+    ├── testing/
+    └── defects/
+
+docs/
+├── planning/
+├── design/tasks/
+├── testing/
+├── deployment/
+└── defects/
+```
+
+### 2. Initialize State
+
+Sets `.forge/state.yaml`:
+```yaml
+project_phase: 0
+phase_history: []
+features: {}
+context:
+  last_updated: null
+  current_task: null
+  current_sub_phase: null
+```
+
+### 3. Copy Default Config
+
+Creates `.forge/config.yaml` with defaults:
+- Model tiers
+- Phase mappings
+- Quality thresholds
+- Task categories
+- Gate behavior
+
+### 4. Copy Templates
+
+Creates document templates in `.forge/templates/`:
+- Planning templates (4 docs)
+- Design templates (task template)
+- Testing templates
+- Defect templates
+
+### 5. Create Symlinks
+
+Links `.opencode/` to `.forge/adapters/opencode/`:
+```bash
+ln -s .forge/adapters/opencode/skills .opencode/skills
+ln -s .forge/adapters/opencode/commands .opencode/commands
+ln -s .forge/adapters/opencode/agents .opencode/agents
+```
+
+### 6. Scan Existing Artifacts
+
+Detects existing project files:
+- `docs/planning/*`
+- `docs/design/*`
+- Existing task documents
+
+Offers to import into state.
+
+## Flags
+
+- `--force` - Overwrite existing .forge directory
+- `--no-links` - Don't create .opencode symlinks
+- `--no-templates` - Don't copy templates
+
+## Prerequisites
+
+- Empty or fresh project directory
+- No existing .forge directory (unless --force)
+
+## Next Steps
+
+After init:
+1. Review `.forge/config.yaml` and customize
+2. Use `/forge-1-plan` to begin Phase 1
+
+## Notes
+
+If running in existing project:
+1. Scan for existing artifacts
+2. Offer to import them
+3. Update state accordingly

package/commands/forge-status.md

@@ -0,0 +1,94 @@
+---
+description: Forge AI - Diagnose and recover from state inconsistencies
+agent: forge-orchestrator
+---
+
+# Forge Status - State Recovery
+
+Diagnose and recover from Forge state inconsistencies.
+
+## Usage
+
+`/forge-status`
+
+## What It Checks
+
+### 1. Phase Consistency
+- Verify `project_phase` matches phase_history
+- Check for orphaned phase entries
+- Validate phase transitions are logical
+
+### 2. Feature State Integrity
+- Validate all features have required fields
+- Check current_sub_phase is valid (1_discover through 8_summarise)
+- Verify task_document paths exist
+
+### 3. Task Document References
+- Verify all referenced task documents exist
+- Check for broken references
+- Validate frontmatter consistency
+
+### 4. Rework Tracking
+- Report rework loop counts
+- Warn if approaching thresholds
+
+### 5. Context Budget
+- Report context usage
+- Warn if approaching limits
+
+## Diagnostic Output Format
+
+```
+Forge Status Report
+====================
+
+Phase: 3 (Development)
+Phase History:
+  - Phase 1: complete ✓
+  - Phase 2: complete ✓
+  - Phase 3: in-progress (started: 2026-03-22)
+
+Active Features: 2
+  - auth-system: 5_implement (loops: 1/3)
+  - api-gateway: 3_clarify (loops: 0/3)
+
+Issues Found: 1
+  ⚠ WARN: docs/design/tasks/legacy-task.md references non-existent task
+
+Context Budget: 45,000 / 150,000 chars (30%)
+```
+
+## Recovery Actions
+
+| Issue | Recovery |
+|-------|----------|
+| Missing phase history | Rebuild from artifacts |
+| Invalid sub-phase | Reset to valid state |
+| Broken task ref | Remove orphaned reference |
+| Corrupted state | Offer state reset |
+
+## Interactive Flow
+
+1. Run diagnostics
+2. Present issues found
+3. Offer recovery options:
+   - `[F]ix` - Apply automatic fixes
+   - `[M]anual` - Fix manually
+   - `[I]gnore` - Continue anyway
+4. Apply selected fix
+5. Confirm recovery
+
+## Automatic Fixes
+
+These can be applied automatically:
+- Remove orphaned feature references
+- Reset invalid sub-phase values
+- Add missing phase history entries
+- Fix corrupted YAML (basic)
+
+## Manual Fixes Required
+
+These require user intervention:
+- State file reset
+- Phase transition correction
+- Feature removal decisions

package/commands/forge.md

@@ -0,0 +1,77 @@
+---
+description: Forge AI - Structured AI-augmented coding methodology
+agent: forge-orchestrator
+---
+
+# Forge AI
+
+Forge AI is a structured methodology for AI-augmented coding built on 6 project phases.
+
+## Project Phases
+
+| Phase | Command | Description |
+|-------|---------|-------------|
+| 1 | `/forge-1-plan` | Planning and requirement analysis |
+| 2 | `/forge-2-design` | System design and task breakdown |
+| 3 | `/forge-3-build` | Development via Feature Dev lifecycle |
+| 4 | `/forge-4-test` | Functional testing and UAT |
+| 5 | `/forge-5-deploy` | Deployment |
+| 6 | `/forge-6-maintain` | Maintenance triage, routing, and audit |
+
+## Utility Commands
+
+| Command | Description |
+|---------|-------------|
+| `/forge-init` | Initialize Forge in a new project |
+| `/forge-status` | Diagnose and recover from state inconsistencies |
+
+## Feature Development (Phase 3 Sub-Phases)
+
+| Sub-Phase | Command | Description |
+|-----------|---------|-------------|
+| 1 | `/forge-3-build-1-discover` | Understand what needs to be built |
+| 2 | `/forge-3-build-2-explore` | Explore relevant existing code |
+| 3 | `/forge-3-build-3-clarify` | Resolve ambiguities |
+| 4 | `/forge-3-build-4-approach` | Design/validate approach |
+| 5 | `/forge-3-build-5-implement` | Build the feature |
+| 6 | `/forge-3-build-6-review` | Quality review |
+| 7 | `/forge-3-build-7-validate` | Test validation |
+| 8 | `/forge-3-build-8-summarise` | Document accomplishments |
+
+## Current State
+
+@.forge/state.yaml
+
+## Quick Start
+
+1. Run `/forge-1-plan` to begin Phase 1: Planning
+2. Progress through phases as needed
+3. Use `/forge-3-build` for development with Feature Dev lifecycle
+
+## Flags
+
+- `--only {sub-operation}` - Run specific sub-operation within a phase
+- `--model {tier}` - Override model tier (high, medium, low)
+- `--task {slug}` - Work on specific task (for Phase 3)
+
+## Design Principles
+
+- Single Responsibility — each tool does one thing well
+- Composability — tools can be chained
+- Minimal Coupling — tools depend on artifact structure
+- Transparency — log all actions and changes
+- Deterministic tooling preferred — use linters, formatters, validators
+
+## Git Commit Hooks
+
+After completing sub-phases, commit your changes:
+
+```bash
+git add -A
+git commit -m "forge: {type} - {description}"
+```
+
+## Learn More
+
+See `.forge/state.yaml` for current project state.
+See `.forge/config.yaml` for Forge configuration.

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD,eAAO,MAAM,OAAO,EAAE,MAErB,CAAC;AAEF,eAAe,OAAO,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAe,MAAM,qBAAqB,CAAC;AA0E/D,eAAO,MAAM,OAAO,EAAE,MA4GrB,CAAC;AAEF,eAAe,OAAO,CAAC"}