@jadeit/forge-ai 1.2.1 → 1.4.0

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": "1.2.1",
+  "version": "1.4.0",
   "description": "Forge AI - Structured AI-augmented coding methodology for OpenCode",
   "main": "dist/index.js",
   "type": "module",

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.

package/skills/forge-build-approach/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: forge-build-approach
+description: Forge Feature Dev - Sub-phase 4: Design/validate approach
+license: MIT
+compatibility: opencode
+---
+
+# Forge AI: Phase 3 - Sub-phase 4: Approach
+
+Invoke the `@forge-approach` subagent for Feature Dev sub-phase 4.
+
+## Purpose
+
+Design (greenfield) or validate (brownfield) the implementation approach.
+
+## Approach Activities
+
+### Brownfield Mode
+- Validate existing approach against current code
+- Check for changes in dependencies or patterns
+- Flag any deviations from original design
+
+### Greenfield Mode
+- Identify components needed
+- Define interfaces between components
+- Choose appropriate patterns (SOLID principles)
+- Plan file structure and module boundaries
+
+## Documentation
+
+Document in task document:
+- Implementation plan with steps
+- Micro-decisions with rationale
+- File structure
+- SOLID compliance approach
+
+## Next Steps
+
+After approach confirmed by user, proceed to `/forge-build-implement`.

package/skills/forge-build-clarify/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: forge-build-clarify
+description: Forge Feature Dev - Sub-phase 3: Resolve ambiguities
+license: MIT
+compatibility: opencode
+---
+
+# Forge AI: Phase 3 - Sub-phase 3: Clarify
+
+Invoke the `@forge-clarify` subagent for Feature Dev sub-phase 3.
+
+## Purpose
+
+Fill in gaps and resolve ambiguities. Output updates the task document.
+
+## Clarify Activities
+
+- Review findings from discover and explore phases
+- Identify gaps in requirements
+- Form questions for user
+- Update acceptance criteria
+
+## Question Format
+
+Present questions clearly:
+```
+**Q1:** [Specific question]
+**Context:** [Why this matters]
+**Options:** [If multiple solutions exist]
+```
+
+## Prioritization
+
+- **Must** - Blockers for implementation
+- **Should** - Important for optimal solution
+- **Could** - Nice to have clarification
+
+## Next Steps
+
+After clarify complete (all "Must" questions answered), proceed to `/forge-build-approach`.

package/skills/forge-build-discover/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: forge-build-discover
+description: Forge Feature Dev - Sub-phase 1: Understand what needs to be built
+license: MIT
+compatibility: opencode
+---
+
+# Forge AI: Phase 3 - Sub-phase 1: Discover
+
+Invoke the `@forge-discover` subagent for Feature Dev sub-phase 1.
+
+## Purpose
+
+Understand what needs to be built by orienting within existing context.
+
+## Discover Activities
+
+- Read existing task document (brownfield) or create new one (greenfield)
+- Understand the problem, scope, and approach
+- Identify what needs clarification
+
+## Operating Modes
+
+**Brownfield:** Task document exists with implementation detail
+**Greenfield:** No task document or stub only
+
+## Mode Detection
+
+1. Check for task document in `docs/design/tasks/{task-slug}.md`
+2. Propose mode with reasoning
+3. Wait for confirmation before proceeding
+
+## Next Steps
+
+After discover complete, proceed to `/forge-build-explore`.

package/skills/forge-build-explore/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: forge-build-explore
+description: Forge Feature Dev - Sub-phase 2: Explore relevant existing code
+license: MIT
+compatibility: opencode
+---
+
+# Forge AI: Phase 3 - Sub-phase 2: Explore
+
+Invoke the `@forge-explore` subagent for Feature Dev sub-phase 2.
+
+## Purpose
+
+Understand relevant existing code, patterns, and conventions.
+
+## Explore Activities
+
+- Read affected modules from task frontmatter
+- Identify coding style and patterns
+- Find related code and shared utilities
+- Understand dependencies and integration points
+
+## Context
+
+Load from task document:
+- `affected_modules` - directories to explore
+- `dependencies` - related task documents
+
+## Next Steps
+
+After explore complete, proceed to `/forge-build-clarify`.

package/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/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/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/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/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/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/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/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 |