@jadeit/forge-ai 0.0.0 → 1.4.0

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-context-loader/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: forge-context-loader
+description: Load minimum necessary context for Forge operations based on current phase
+license: MIT
+compatibility: opencode
+metadata:
+  audience: forge-users
+  workflow: phase-execution
+---
+
+# Forge Context Loader
+
+Load the **minimum context needed** for the current Forge operation, not everything the project has ever produced.
+
+## Context Loading Rules
+
+| Phase | Load These |
+|-------|-----------|
+| `forge 1:plan` | User input, existing README or project brief |
+| `forge 2:design` | All Phase 1 outputs. Existing codebase structure if applicable |
+| `forge 3:build` | Specific task doc, technology & architecture doc, relevant source files |
+| `forge 4:test` | User stories, task docs for implemented features, test results |
+| `forge 5:deploy` | Technology & architecture doc, infrastructure-related task docs |
+| `forge 6:maintain` | Specific error/incident context, relevant source files, defect history |
+
+## Context by Sub-Phase
+
+| Sub-Phase | Additional Context |
+|-----------|-------------------|
+| `3:build 1:discover` | Task document, state file |
+| `3:build 2:explore` | Affected modules from task, existing codebase |
+| `3:build 3:clarify` | Discovery findings, exploration notes |
+| `3:build 4:approach` | Task document, design decisions |
+| `3:build 5:implement` | Task document, approach plan |
+| `3:build 6:review` | Implementation, test files, lint config |
+| `3:build 7:validate` | Task document, test files, coverage reports |
+| `3:build 8:summarise` | All phase artifacts |
+
+## Usage
+
+### Loading Context for Phase 1
+```
+Read: README.md, PROJECT_SCOPE.md (if exists)
+```
+
+### Loading Context for Phase 2
+```
+Read: docs/planning/project-scope.md
+Read: docs/planning/user-stories.md
+Read: docs/planning/implementation-plan.md
+Read: docs/planning/technology-and-architecture.md
+Glob: src/**/* (codebase structure)
+```
+
+### Loading Context for Feature Dev
+```
+Read: .forge/state.yaml
+Read: docs/planning/technology-and-architecture.md
+Read: docs/design/tasks/{task-slug}.md
+Glob: {affected_modules} (from task frontmatter)
+```
+
+## Context Budget
+
+Read `.forge/config.yaml` for context_budget settings:
+```yaml
+context_budget:
+  warning_threshold: 150000  # Warn if exceeded
+  max_threshold: 180000       # Hard limit
+```
+
+### If Context Exceeds Threshold
+
+1. **Warn the user** about the exceeded context budget
+2. **Suggest trimming strategies:**
+   - Focus on most recent changes
+   - Remove boilerplate and generated files
+   - Exclude node_modules, vendor, etc.
+3. **Prioritise:**
+   - Task document over other documents
+   - Core business logic over infrastructure
+   - Tests for the specific feature over full test suite
+
+## Implementation
+
+Use Glob and Grep to identify relevant files:
+
+```bash
+# Get affected modules from task frontmatter
+# Glob those directories
+# Grep for key patterns if needed
+```
+
+## Principles
+
+1. **Minimum Viable Context** - Only load what is necessary
+2. **Lazy Loading** - Load files when needed, not upfront
+3. **Incremental** - Context grows as you progress through sub-phases
+4. **Clean State** - Reset context when starting new phases/tasks

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 |