@jadeit/forge-ai 0.0.0 → 1.4.0

package/dist/skills/forge-build-implement/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: forge-build-implement
+description: Forge Feature Dev - Sub-phase 5: Build the feature
+license: MIT
+compatibility: opencode
+---
+
+# Forge AI: Phase 3 - Sub-phase 5: Implement
+
+Invoke the `@forge-implement` subagent for Feature Dev sub-phase 5.
+
+## Purpose
+
+Build the feature following the validated approach.
+
+## Implementation Order
+
+1. Foundation (types, constants, utilities)
+2. Core domain/business logic
+3. Data layer (if applicable)
+4. API layer (if applicable)
+5. Integration points
+6. Tests
+
+## Quality Checks
+
+After implementation:
+- Run linting
+- Run type checking
+- Write tests
+
+## Flags
+
+- `--task {slug}` - Specific task to implement
+- `--model {tier}` - Override model tier
+
+## Next Steps
+
+After implementation complete, proceed to `/forge-build-review`.

package/dist/skills/forge-build-review/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: forge-build-review
+description: Forge Feature Dev - Sub-phase 6: Quality review
+license: MIT
+compatibility: opencode
+---
+
+# 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-build-implement`
+- **Approach issues** → Loop to `/forge-build-approach`
+
+## Next Steps
+
+After review passes, proceed to `/forge-build-validate`.

package/dist/skills/forge-build-summarise/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: forge-build-summarise
+description: Forge Feature Dev - Sub-phase 8: Document accomplishments
+license: MIT
+compatibility: opencode
+---
+
+# 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 use `/forge-test` for Phase 4

package/dist/skills/forge-build-validate/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: forge-build-validate
+description: Forge Feature Dev - Sub-phase 7: Test validation
+license: MIT
+compatibility: opencode
+---
+
+# 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: ... | *.test.ts | ✓ |
+| AC2: ... | - | ✗ |
+
+### 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-build-implement` for test fixes
+
+## Next Steps
+
+After validation passes, proceed to `/forge-build-summarise`.

package/dist/skills/forge-deploy/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: forge-deploy
+description: Forge AI Phase 5 - Deployment
+license: MIT
+compatibility: opencode
+---
+
+# 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-maintain` for Phase 6: Maintenance.

package/dist/skills/forge-design/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: forge-design
+description: Forge AI Phase 2 - System design and task breakdown
+license: MIT
+compatibility: opencode
+---
+
+# Forge AI: Phase 2 - Design
+
+Invoke the `@forge-design` agent to begin Phase 2: Design.
+
+## What Happens
+
+1. Phase 1 artifacts are loaded and reviewed
+2. Design agent creates required documents:
+   - `docs/design/design-decisions.md`
+   - `docs/design/task-list.md`
+   - `docs/design/tasks/{task-slug}.md` (one per task)
+3. Agent validates all task documents have required frontmatter
+4. State is updated in `.forge/state.yaml`
+5. You confirm transition to Phase 3
+
+## Phase 2 Outputs
+
+| Document | Purpose |
+|----------|---------|
+| design-decisions.md | Documented design decisions |
+| task-list.md | Summary list of all tasks |
+| tasks/{task-slug}.md | One document per task with implementation detail |
+
+## Task Document Requirements
+
+Each task document includes:
+- Required frontmatter (title, status, mode, complexity, categories)
+- Summary / Objective
+- Acceptance Criteria (testable)
+- Implementation Detail (illustrative code permitted)
+- Testing Criteria
+
+## Flags
+
+- `--only {task}` - Work on specific task only
+- `--model {tier}` - Override model tier
+
+## Prerequisites
+
+Phase 1 must be complete. Check `.forge/state.yaml`.
+
+If prerequisites not met, warning is shown but you may override and proceed.
+
+## Next Steps
+
+After Phase 2 complete, use `/forge-build` for Phase 3: Development.

package/dist/skills/forge-init/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: forge-init
+description: Forge AI - Initialize Forge in a new project
+license: MIT
+compatibility: opencode
+---
+
+# Forge Init - Bootstrap Command
+
+Initialize Forge AI in a new project directory.
+
+## What It Does
+
+### 1. Create Directory Structure
+
+Creates:
+```
+.forge/
+├── config.yaml
+├── state.yaml
+└── 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. 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-templates` - Don't copy templates
+
+## Next Steps
+
+After init:
+1. Review `.forge/config.yaml` and customize
+2. Use `/forge-plan` to begin Phase 1

package/dist/skills/forge-maintain/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: forge-maintain
+description: Forge AI Phase 6 - Maintenance triage, routing, and audit
+license: MIT
+compatibility: opencode
+---
+
+# 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-design` | Brownfield |
+| Implementation bug | `/forge-build` | Greenfield |
+| Configuration issue | `/forge-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 |

package/dist/skills/forge-plan/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: forge-plan
+description: Forge AI Phase 1 - Planning and requirement analysis
+license: MIT
+compatibility: opencode
+---
+
+# Forge AI: Phase 1 - Planning
+
+Invoke the `@forge-plan` agent to begin Phase 1: Planning.
+
+## What Happens
+
+1. Context is loaded (existing README/brief if present)
+2. Planning agent creates required documents:
+   - `docs/planning/project-scope.md`
+   - `docs/planning/user-stories.md`
+   - `docs/planning/implementation-plan.md`
+   - `docs/planning/technology-and-architecture.md`
+3. Agent validates all required artifacts exist
+4. State is updated in `.forge/state.yaml`
+5. You confirm transition to Phase 2
+
+## Phase 1 Outputs
+
+| Document | Purpose |
+|----------|---------|
+| project-scope.md | Project aim, high-level design, technology choices |
+| user-stories.md | User stories that drive development |
+| implementation-plan.md | High-level phases to be implemented |
+| technology-and-architecture.md | Tech choices and architecture (C4 Model) |
+
+## Constraints
+
+- NO executable code, scaffolding, or infrastructure
+- Illustrative code snippets ARE permitted
+- Use Mermaid diagrams for architecture
+
+## Flags
+
+- `--only {artifact}` - Work on specific artifact only
+  - Options: project-scope, user-stories, implementation-plan, technology
+
+## Prerequisites
+
+None — Phase 1 is the starting point.
+
+## Next Steps
+
+After Phase 1 complete, use `/forge-design` for Phase 2: Design.

package/dist/skills/forge-status/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: forge-status
+description: Forge AI - Diagnose and recover from state inconsistencies
+license: MIT
+compatibility: opencode
+---
+
+# Forge Status - State Recovery
+
+Diagnose and recover from Forge state inconsistencies.
+
+## 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)
+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
+```
+
+## 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 |

package/dist/skills/forge-test/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: forge-test
+description: Forge AI Phase 4 - Functional testing and UAT
+license: MIT
+compatibility: opencode
+---
+
+# 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-deploy` for Phase 5: Deployment.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jadeit/forge-ai",
-  "version": "0.0.0",
+  "version": "1.4.0",
   "description": "Forge AI - Structured AI-augmented coding methodology for OpenCode",
   "main": "dist/index.js",
   "type": "module",
@@ -8,7 +8,11 @@
     ".": "./dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "agents",
+    "commands",
+    "skills",
+    "templates"
   ],
   "scripts": {
     "build": "bun run build.ts",
@@ -32,7 +36,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/jadeit/forge-ai.git"
+    "url": "git+https://github.com/jadeit/forge-ai.git"
   },
   "publishConfig": {
     "access": "public"

package/skills/forge-build/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: forge-build
+description: Forge AI Phase 3 - Development via Feature Dev lifecycle
+license: MIT
+compatibility: opencode
+---
+
+# Forge AI: Phase 3 - Development
+
+Invoke the `@forge-build` agent to begin Feature Development.
+
+## Feature Dev Lifecycle
+
+| Sub-Phase | Command | Description |
+|-----------|---------|-------------|
+| 1 | `/forge-build-discover` | Understand what needs to be built |
+| 2 | `/forge-build-explore` | Explore relevant existing code |
+| 3 | `/forge-build-clarify` | Resolve ambiguities |
+| 4 | `/forge-build-approach` | Design/validate approach |
+| 5 | `/forge-build-implement` | Build the feature |
+| 6 | `/forge-build-review` | Quality review |
+| 7 | `/forge-build-validate` | Test validation |
+| 8 | `/forge-build-summarise` | Document accomplishments |
+
+## Usage
+
+Run `/forge-build` for full lifecycle, or use specific sub-phase commands.
+
+## 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-test` for Phase 4: Testing.