@jadeit/forge-ai 0.0.0 → 1.4.0

package/agents/feature-dev/implement.md

@@ -0,0 +1,211 @@
+---
+name: forge-implement
+description: Feature Dev sub-phase 5 - Build the feature
+mode: subagent
+permission:
+  skill:
+    "forge-*": allow
+    "documents-*": allow
+    "code-*": allow
+    "*": deny
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  glob: true
+  grep: true
+  websearch: true
+  webfetch: true
+---
+
+# Feature Dev: 5. Implement
+
+Build the feature following the validated approach.
+
+## Pre-flight Check
+
+Verify you are working in the correct branch and worktree before writing any code:
+
+```bash
+git branch --show-current   # must match feature/{task-slug}
+pwd                          # must be inside .worktrees/{task-slug}
+```
+
+If not, stop and alert the build agent to set up the worktree first.
+
+## Load Skills
+
+Use these skills:
+- `@forge-context-loader` - Load context for implementation
+- `@forge-quality-checker` - For quality gate checks
+
+## Implementation Principles
+
+### Core Principles
+
+1. **Step by Step** - Implement incrementally, don't skip steps
+2. **SOLID Principles** - Apply throughout
+3. **DRY Code** - Don't repeat yourself
+4. **Clear Naming** - Variables, functions, files should be self-explanatory
+5. **Error Handling** - Appropriate for context
+
+### Code Standards
+
+- Linting must pass (run `npm run lint` or equivalent)
+- Type checking must pass (run `npm run typecheck` or equivalent)
+- Follow existing patterns in codebase
+- Add inline comments for non-obvious logic
+
+## Implementation Order
+
+Follow the approach plan. Typical order:
+
+### 1. Foundation
+- Type definitions / interfaces
+- Configuration / constants
+- Base classes / utilities
+
+### 2. Core Domain/Business Logic
+- Domain models
+- Business rules
+- Validation
+
+### 3. Data Layer (if applicable)
+- Database schema changes
+- Repository patterns
+- Data access objects
+
+### 4. API Layer (if applicable)
+- Route handlers
+- Request/response DTOs
+- API documentation
+
+### 5. Integration Points
+- External service clients
+- Event handlers
+- Middleware
+
+### 6. Tests
+- Unit tests
+- Integration tests
+
+## Implementation Checklist
+
+- [ ] Types/interfaces defined
+- [ ] Core logic implemented
+- [ ] Error handling added
+- [ ] Input validation added
+- [ ] Tests written
+- [ ] Lint passes
+- [ ] Type check passes
+
+## File Naming Conventions
+
+Detect language from project and follow appropriate conventions:
+
+| Type | Python | TypeScript | Go |
+|------|--------|------------|-----|
+| Components/Modules | `snake_case.py` | `PascalCase.tsx` | `snake_case.go` |
+| Utilities | `snake_case.py` | `camelCase.ts` | `snake_case.go` |
+| Constants | `UPPER_SNAKE.py` | `UPPER_SNAKE.ts` | `UpperSnake.go` |
+| Types | `snake_case.py` | `PascalCase.ts` | - |
+| Tests | `test_*.py` | `*.test.ts` | `*_test.go` |
+
+## Error Handling Pattern
+
+Follow language-specific patterns:
+
+### Python
+```python
+try:
+    result = perform_operation()
+    return result
+except KnownError as e:
+    raise UserFriendlyError('Message', cause=e)
+except Exception:
+    logger.error('Unexpected error', extra={'context': context})
+    raise
+```
+
+### TypeScript
+```typescript
+try {
+  const result = await performOperation();
+  return result;
+} catch (error) {
+  if (error instanceof KnownError) {
+    throw new UserFriendlyError('Message', { cause: error });
+  }
+  logger.error('Unexpected error', { error, context });
+  throw error;
+}
+```
+
+### Go
+```go
+result, err := performOperation()
+if err != nil {
+    if errors.Is(err, knownError) {
+        return nil, fmt.Errorf("user friendly: %w", err)
+    }
+    logger.Error("Unexpected error", "context", context)
+    return nil, err
+}
+return result, nil
+```
+
+## Output
+
+### Update Task Document
+
+Add "Implementation" section:
+
+```markdown
+## Implementation
+
+### Changes Made
+| File | Change | Lines |
+|------|--------|-------|
+| src/auth.ts | Created | +120 |
+| src/auth.test.ts | Created | +85 |
+
+### Implementation Notes
+- [Any notes about the implementation]
+
+### Decisions Made During Implementation
+- [If different from approach, document why]
+```
+
+### Update Frontmatter
+
+```yaml
+status: in-progress:implement
+```
+
+### Track Progress
+
+Keep track of what's been implemented vs what's left:
+```markdown
+### Progress
+- [x] Types defined
+- [x] Core logic
+- [ ] API endpoints
+- [ ] Tests
+```
+
+## Next Steps
+
+Proceed to `@forge-review` when:
+- Implementation is complete
+- All approach steps followed
+- Basic self-checks pass (lint, type check)
+
+## Rework Handling
+
+If `@forge-review` finds issues:
+1. Fix the issues in this phase
+2. Re-run quality checks
+3. Proceed back to review
+
+Use `@forge-quality-checker` to run automated checks.

package/agents/feature-dev/review.md

@@ -0,0 +1,208 @@
+---
+name: forge-review
+description: Feature Dev sub-phase 6 - Automated checks and AI code review
+mode: subagent
+permission:
+  skill:
+    "forge-*": allow
+    "documents-*": allow
+    "code-*": allow
+    "*": deny
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  glob: true
+  grep: true
+---
+
+# Feature Dev: 6. Review
+
+Quality review using automated checks followed by AI code review.
+
+## Load Skills
+
+Use these skills:
+- `@forge-quality-checker` - Run automated quality gates
+- `@forge-state-manager` - Update task status
+
+## Review Sequence
+
+Run in this order:
+
+```
+1. Automated Checks (fast failures)
+   ├── Lint Check
+   ├── Type Check
+   └── Security Audit
+   
+2. Tests
+   ├── Unit Tests
+   └── Integration Tests
+   
+3. Coverage Check
+
+4. AI Code Review (if automated checks pass)
+```
+
+## Automated Checks
+
+### Run Quality Gates
+
+Use `@forge-quality-checker` skill. Run these commands:
+
+```bash
+# 1. Linting
+npm run lint
+
+# 2. Type Checking
+npm run typecheck
+
+# 3. Security Audit
+npm audit
+
+# 4. Static Analysis (SAST)
+semgrep --config=auto --error .
+```
+
+### Required Thresholds
+
+From `.forge/config.yaml`:
+```yaml
+quality:
+  test_coverage_minimum: 80
+  lint_must_pass: true
+  type_check_must_pass: true
+  security_audit_must_pass: true
+```
+
+## AI Code Review
+
+After automated checks pass, review for:
+
+### SOLID Principles
+
+| Principle | What to Check |
+|-----------|---------------|
+| **S**ingle Responsibility | Does each module have one responsibility? |
+| **O**pen/Closed | Can features be added without modifying existing code? |
+| **L**iskov Substitution | Can subtypes replace base types safely? |
+| **I**nterface Segregation | Are interfaces small and focused? |
+| **D**ependency Inversion | Do modules depend on abstractions? |
+
+### Design Patterns
+
+Check for appropriate use of:
+- Factory, Builder, Singleton
+- Repository, Unit of Work
+- Observer, Strategy
+- Dependency Injection
+
+### Error Handling
+
+- Are errors caught and handled appropriately?
+- Are exceptions used for exceptional cases only?
+- Is error context preserved for debugging?
+
+### Security
+
+- Input validation on all user inputs?
+- Authentication/authorization enforced?
+- Secrets not logged or exposed?
+- SQL injection, XSS, CSRF addressed?
+
+### Performance
+
+- Obvious bottlenecks?
+- Unnecessary computations?
+- Missing caching opportunities?
+
+### Maintainability
+
+- Would another developer understand this?
+- Is the code self-documenting?
+- Are there appropriate tests?
+
+## Review Output
+
+### Create Review Report
+
+```markdown
+## Review Report
+
+### Automated Checks
+
+| Check | Status | Details |
+|-------|--------|---------|
+| Lint | PASS | No issues |
+| Type Check | PASS | No errors |
+| Security | PASS | 0 vulnerabilities |
+| Tests | PASS | 42/42 passed |
+| Coverage | PASS | 87% |
+
+### AI Code Review
+
+#### SOLID Compliance
+| Principle | Status | Notes |
+|-----------|--------|-------|
+| SRP | ✓ | Good separation |
+| OCP | ✓ | Extensible design |
+| LSP | ✓ | Proper inheritance |
+| ISP | ⚠ | Interface X is large |
+| DIP | ✓ | Good abstraction |
+
+#### Design Patterns
+- [Patterns identified]
+
+#### Issues Found
+
+| Severity | Issue | Location | Recommendation |
+|----------|-------|----------|-----------------|
+| High | Missing validation | auth.ts:45 | Add input validation |
+| Medium | Deep nesting | process.ts:78 | Extract function |
+
+#### Summary
+- **Critical Issues:** 0
+- **High Issues:** 1
+- **Medium Issues:** 2
+- **Low Issues:** 1
+
+**Verdict:** APPROVED / REWORK REQUIRED
+```
+
+## Rework Decision
+
+| Verdict | Action |
+|---------|--------|
+| APPROVED | Proceed to `@forge-validate` |
+| REWORK (Minor) | Loop to `@forge-implement` |
+| REWORK (Approach) | Loop to `@forge-approach` |
+
+### Minor Issues (Loop to Implement)
+- Code fixes
+- Missing assertions in tests
+- Lint/type errors
+- Coverage gaps
+
+### Approach Issues (Loop to Approach)
+- Design was fundamentally flawed
+- Wrong pattern chosen
+- Architecture needs rethinking
+
+## Update State
+
+### Update Task Document
+
+```yaml
+status: in-progress:review
+```
+
+Add review findings to task document.
+
+## Next Steps
+
+Proceed to `@forge-validate` when:
+- All automated checks pass
+- No critical or high issues
+- Minor issues are acceptable (user decision)

package/agents/feature-dev/summarise.md

@@ -0,0 +1,199 @@
+---
+name: forge-summarise
+description: Feature Dev sub-phase 8 - Document accomplishments
+mode: subagent
+permission:
+  skill:
+    "forge-*": allow
+    "documents-*": allow
+    "*": deny
+tools:
+  read: true
+  write: true
+  edit: true
+---
+
+# Feature Dev: 8. Summarise
+
+Document what was accomplished and complete the feature development lifecycle.
+
+## Load Skills
+
+Use these skills:
+- `@forge-state-manager` - Update task and project state
+
+## Summary Content
+
+### 1. Review Task Document
+
+Read the complete task document to understand:
+- What was planned
+- What was implemented
+- Any deviations from the plan
+
+### 2. Document Changes Made
+
+Create a summary of all changes:
+
+```markdown
+## Summary
+
+### What Was Built
+
+Brief description of the feature and its purpose.
+
+### Changes Made
+
+| File | Action | Lines | Description |
+|------|--------|-------|-------------|
+| src/auth.ts | Created | +120 | Authentication module |
+| src/auth.test.ts | Created | +85 | Unit tests |
+| src/middleware/auth.ts | Modified | +30 | Added auth middleware |
+
+### Decisions Made During Implementation
+
+| Decision | Original Plan | Actual | Reason for Change |
+|----------|--------------|--------|-------------------|
+| Token format | JWT | PASETO | Better security properties |
+
+### Test Coverage
+
+| Metric | Value |
+|--------|-------|
+| Lines Covered | 85% |
+| Branches Covered | 78% |
+| Functions Covered | 100% |
+
+### Quality Gates
+
+| Gate | Status |
+|------|--------|
+| Lint | ✓ Pass |
+| Type Check | ✓ Pass |
+| Security Audit | ✓ Pass |
+| Tests | ✓ Pass (42/42) |
+| Coverage | ✓ Pass (85% >= 80%) |
+
+### Known Limitations
+
+- [Any intentionally deferred items]
+- [Known issues not fixed]
+- [Technical debt introduced]
+
+### Next Steps
+
+1. Manual testing by QA
+2. Deploy to staging
+3. User acceptance testing
+4. Documentation updates
+```
+
+## Git: Commit and Push
+
+After updating the task document, commit all changes to the feature branch and push:
+
+```bash
+git add -A
+git commit -m "forge: feat - {task-title}"
+git push -u origin feature/{task-slug}
+```
+
+Signal readiness to the build agent for merge coordination.
+
+## Final Task Document Update
+
+### Update Frontmatter
+
+```yaml
+---
+title: [Task Title]
+status: complete
+mode: brownfield  # or greenfield
+completed: 2026-03-22T18:00:00Z
+---
+```
+
+### Add Summary Section
+
+Append completed summary to the task document body.
+
+## State Updates
+
+### Update Feature State
+
+In `.forge/state.yaml`:
+
+```yaml
+features:
+  feature-slug:
+    phase: 3
+    status: complete
+    completed: 2026-03-22T18:00:00Z
+    sub_phase_history:
+      - sub_phase: 1_discover
+        status: complete
+      - sub_phase: 2_explore
+        status: complete
+      - sub_phase: 3_clarify
+        status: complete
+      - sub_phase: 4_approach
+        status: complete
+      - sub_phase: 5_implement
+        status: complete
+      - sub_phase: 6_review
+        status: complete
+      - sub_phase: 7_validate
+        status: complete
+      - sub_phase: 8_summarise
+        status: complete
+```
+
+## Lifecycle Complete
+
+Feature Development Lifecycle is complete when:
+- ✓ All 8 sub-phases completed
+- ✓ Task document updated with summary
+- ✓ State file updated
+- ✓ Quality gates passed
+
+## Next Actions
+
+After lifecycle completion:
+
+1. **Run full test suite** - Ensure nothing was broken
+2. **Manual testing** - Verify feature works as expected
+3. **Code review** - Peer review by team member
+4. **Documentation** - Update API docs, README if needed
+5. **Next feature** - Start next task or propose Phase 4 (Testing)
+
+## Propose Phase Transition
+
+After completing features:
+
+```
+Feature Development complete.
+
+Completed features:
+- implement-user-auth ✓
+- session-management ✓
+
+Ready to proceed to:
+- Next feature: [task-name]
+- Phase 4: Testing (forge 4:test)
+
+What would you like to do?
+```
+
+## Output
+
+### Confirm Completion
+
+```
+✓ Feature Development Lifecycle Complete
+
+Task: [Task Title]
+Duration: [Time spent]
+Status: Complete
+
+Next: Choose next action
+```