Skip to content

workflow.md

Latest commit

 

History

History
298 lines (225 loc) · 12.8 KB

workflow.md

File metadata and controls

298 lines (225 loc) · 12.8 KB

Harness Skill Workflow: Project Initialization + Feature Implementation

Date: 2026-05-03 Scope: Complete workflow for the Harness skill ecosystem (including graph/explore/design-review/ai-implementation-integrity enhancements)

1. New Project Initialization (Harness)

Trigger: User says "harness" / "项目初始化" / "setup dev environment"

Step 1: Project Analysis

  • Scan root directory → identify language/framework/build tools
  • Detect AI tool → determine instruction file name (Claude Code → CLAUDE.md)
  • Output project profile → user confirms

Step 2: Skill Ecosystem Installation & Hook Configuration

2.1 Scan ~/.claude/skills/ → show [OK/NO] checklist
2.2 Install bundled skills (symlink)
2.2b Install external cores (superpowers / planning-with-files / claudeception)
2.3 Configure hooks
     - superpowers: SessionStart
     - planning-with-files: UserPromptSubmit / PreToolUse / PostToolUse / Stop
     - claudeception: UserPromptSubmit
2.4 Skill factory usage guide
2.5 Project-specific Skill check
2.6 Dev tool detection
     - Detect code-review-graph:
       python -c "import code_review_graph.tools"
       - Available → register graph + explore skills, inject knowledge graph rules into CLAUDE.md
       - Not available → suggest optional install, skip graph rules
     - Unconditionally register design-review + ai-implementation-integrity

Step 3: Documentation System Generation

  • 3.0 Dispatch 3 parallel Agents to gather code info (no hallucination)
  • 3.1 Generate CLAUDE.md (≤120 lines index)
    • MUST behavioral rules include Surgical Changes
    • Skill reference includes design-review + ai-implementation-integrity
    • Conditional injection: knowledge graph rules (if CRG available)
  • 3.2 Generate docs/ multi-level directory (architecture / implementation / conventions / pitfalls / backlog)

Step 4: Agent Team Design

  • Detect existing Agent Teams → preserve by default
  • Confirm role assignments: A(Architect) / B(Engineer) / C(Tester) / D(Challenger)
  • Generate role definitions → .harness/agents/

Step 5: Development Conventions & Security Standards Injection

  • must-follow.md — coding conventions + Agent behavioral rules (including Surgical Changes)
  • must-not.md — prohibited actions
  • coding-patterns.md — tailored by tech stack
  • secure-coding.md — 15 CWE defenses + OWASP Top 10 + Agent red lines

Step 6: Planning Infrastructure

  • Create .harness/ directory structure (agents / plans / templates)

Step 7: Output Confirmation & Usage Guide

Step 8: Scenario Integration Verification

Verify all 13 scenarios trigger correctly (including new Scenario 12: AI claims completion, Scenario 13: After spec/plan written)

2. Complete Feature Lifecycle

Example: "Add a batch export feature to the project"

Phase 0: Understand Existing Architecture (explore skill)

User: "I want to add a batch export feature"

Graph available?
  YES → /graph view                  ← Open interactive graph in browser (localhost:8765)
        /explore architecture        ← Auto-triggered by CLAUDE.md rules
        Understand module decomposition, entry points, coupling
        /explore impact backend/api/batch.py
        Predict blast radius
  NO  → Traditional approach: read code manually

Phase 1: Brainstorming (HARD-GATE)

superpowers:brainstorming auto-triggers:

  1. Explore project context (read code)
    • Graph-enhanced (hardcoded into local brainstorming skill): /explore architecture + /explore module <target>
  2. One clarifying question at a time → user answers
  3. Propose 2-3 approaches + trade-offs + recommendation
  4. Present design in sections → user confirms each section
  5. Write spec → docs/superpowers/specs/YYYY-MM-DD-<feature>-design.md
  6. Spec self-review (placeholder / contradiction / ambiguity)
    • Graph-enhanced: /explore search <func> verify referenced functions exist + /explore flows verify execution paths
  7. User reviews spec → approves

Phase 1.5: Design Review — Spec Mode

design-review spec <path> auto-triggers (after spec is written):

  • Dispatch independent challenger agent (zero context)
  • Verify every concrete reference in the spec:
    • DB fields → grep models.py
    • API paths → grep api/
    • Config keys → grep get_setting
    • File paths → ls verification
  • Return BLOCKERs + WARNINGs
  • BLOCKERs → fix spec
  • WARNINGs → user decides

Phase 2: Writing Plans

superpowers:writing-plans auto-triggers:

  • Scope check (one spec → one plan)
  • File structure planning
    • Graph-enhanced (hardcoded into local writing-plans skill): /explore impact <file> determines complete Files list, discovers missed affected modules
  • Split into bite-sized tasks (2-5 min each), each task includes: Files / code / tests / verification commands
  • Self-review (spec coverage / placeholders / type consistency)
    • Graph-enhanced: Self-Review step 4 /explore impact verifies blast radius completeness
  • Save → docs/superpowers/plans/YYYY-MM-DD-<feature>.md

After plan is written → design-review plan <path>

  • Independent challenger verifies every import / field / signature
  • Auto-link spec: spec with same date prefix auto-matched, or manually specify --spec <path>
  • Spec coverage verification: produce spec requirement → plan task coverage matrix; uncovered spec requirements are BLOCKERs
  • Fix BLOCKERs → Plan ready for execution

Phase 3: Execution (TDD)

superpowers:subagent-driven-development executes:

Per Task:
  1. Dispatch Implementer subagent
     - RED:  Write failing test
     - GREEN: Minimal implementation to pass test
     - REFACTOR: Clean up
     - Self-review + git commit

  2. Dispatch Spec Reviewer subagent
     - Does code match spec?
     - NO → Implementer fixes → re-review
     - YES → continue

  3. Dispatch Code Quality Reviewer subagent
     - Code quality?
     - Issues → fix → re-review
     - Approved → Mark task complete

Available anytime during development:

  • /explore callers <func> — understand upstream/downstream
  • /explore impact <file> — verify blast radius
  • Surgical Changes rule constrains every diff (only change what must be changed)

Phase 4: Quality Gate (Before Claiming "Done")

ai-implementation-integrity auto-triggers (when claiming done):

Check Method
A. Dead Code Detection rg "new_function(" → has caller?
B. Hallucinated API Detection python -c "from X import Y" → resolves?
C. Formalistic Testing Detection Tests assert real values or just isinstance?
D. Premature "Done" Detection Each spec requirement → points to specific code line?
E. Placeholder Code Detection Function body is pass / return {} / TODO?
F. Chain Connectivity Detection Entry point → intermediate steps → output, all connected?

Also execute Standard Quality Gate:

  • Doc sync: docs/ corresponding modules updated? INDEX.md synced?
  • Code hygiene: no debug output / no unused imports / no temp files
  • Progress update: progress.md reflects actual state
  • Graph-enhanced (hardcoded into local verification-before-completion skill):
    • /explore callers <new_func> verify new function has callers (dead code detection)
    • /explore impact <changed_file> verify blast radius coverage
    • /explore flows verify execution path connectivity

Phase 5: Code Review + Security Review

superpowers:requesting-code-review:

  • Get BASE_SHA / HEAD_SHA
  • Graph-enhanced (hardcoded into local requesting-code-review skill): /explore impact <changed_file> check blast radius, inject results into reviewer context
  • Dispatch code-reviewer subagent
    • Functional correctness / security (OWASP Top 10) / test coverage / performance / backward compatibility
  • Critical → fix immediately
  • Important → fix before proceeding
  • Minor → record

Security Review (when auth/crypto/API changes):

  • Use security-review-skill-for-<project> to audit

Phase 6: Wrap-up

superpowers:finishing-a-development-branch:

  • Choose: merge / squash / rebase
  • Final verification
  • Merge into main

/claudeception auto-evaluates:

  • Is there extractable knowledge from this development session?
    • Pitfall experience → generate .claude/skills/<name>/SKILL.md
    • Non-obvious solutions → generate project Skill
    • No new knowledge → skip

/graph update (optional):

  • Update graph to reflect new code

/graph view (optional):

  • code-review-graph visualize --repo . --serve → open localhost:8765 in browser
  • 4 modes: auto / community / file / full
  • Export: html / svg / obsidian / graphml

3. Key Safeguard Layers

Layer Mechanism Coverage
Hook (system-level) SessionStart / PreToolUse / PostToolUse / Stop AI cannot bypass
CLAUDE.md (instruction-level) MUST / MUST NOT rules Universal across AI tools
Skill Embedding (local enhancement) Direct modification of local superpowers skills, hardcoded graph calls ~95% compliance (skill content loaded each time)
Skill Auto-Matching description semantic matching triggers Auto-activated per scenario
Challenger Agent Independent agent, zero context Eliminates same-session blind spots

Knowledge Graph Dual-Track Integration

Version Mechanism Enforcement Use Case
Published (A) CLAUDE.md conditional injection rules ~80% (text instructions) Distribute to others
Local Practice (A+C) CLAUDE.md + direct modification of local superpowers skills ~95% (skill content-level) Personal daily development

Local skill modification list (located at ~/.claude/plugins/cache/superpowers/5.0.7/skills/):

Skill Injection Point Graph Calls
brainstorming Step 1 project exploration + Spec self-review /explore architecture + /explore module + /explore search + /explore flows
writing-plans File Structure + Self-Review /explore impact
requesting-code-review Pre-dispatch check /explore impact
verification-before-completion New Graph-Enhanced Verification section /explore callers + /explore impact + /explore flows

Core principle: Every phase has an independent verification mechanism, not relying on the previous phase's agent "remembering" to do things right.

  • Brainstorming produces spec → challenger verifies spec
  • Plan produced → challenger verifies plan
  • Implementation complete → ai-implementation-integrity verifies implementation
  • Before claiming done → quality gate + code review

Four layers of independent verification, each gate locked tight.

4. Skill Quick Reference

Workflow Skills (by Phase)

Phase Skill Description
Architecture graph Knowledge graph build/update/status/visualization (browser)
Architecture explore Graph-driven project understanding (architecture/call chains/impact radius)
Design superpowers:brainstorming Requirements → design (HARD-GATE)
Design Review design-review Spec + plan review (independent challenger)
Planning superpowers:writing-plans Design → implementation plan
Planning planning-with-files Plan persistence + state tracking
Execution superpowers:subagent-driven-development Sub-agent per-task execution
Execution superpowers:test-driven-development TDD (RED → GREEN → REFACTOR)
Quality ai-implementation-integrity AI implementation integrity check
Review superpowers:requesting-code-review Code review
Wrap-up superpowers:finishing-a-development-branch Branch integration
Learning claudeception Knowledge extraction & Skill generation

Factory Skills

Skill Description
security-review-skill-creator Generate project-specific security audit Skill
skill-creator General Skill generator
superpowers:writing-skills TDD-style Skill writing

Security Skills

Skill Description
web-vuln-analyzer Web vulnerability analysis
android-vuln-analyzer Android security analysis
sca-ai-denoise SCA vulnerability AI denoising
supply-chain-audit Supply chain poisoning detection
skills-audit Third-party Skill security audit
security-review-skill-for-* Project-specific security audit