agent-method 1.5.12

package/templates/full/registry/features/workflows.yaml

@@ -0,0 +1,404 @@
+# ============================================================
+# LAYER 2: GUIDED WORKFLOWS
+# How features compose into reusable task patterns.
+# ============================================================
+
+workflows:
+  - id: WF-01
+    name: standard-task
+    project_types: [universal]
+    description: >
+      The default workflow for any task. Review current state, plan the work,
+      implement changes, update documentation and context, close with
+      management file updates. This is the backbone pattern.
+    steps:
+      - name: review
+        stage: scope
+        description: Read current state, understand context, identify what needs to change
+        features: [QRY-01, QRY-02, CTX-03]
+        agent_action: >
+          Load entry point + STATE.md (cold start). Classify the query.
+          Load the scoped context. Understand the current position and
+          what decisions have been made. Read relevant files.
+      - name: plan
+        stage: plan
+        description: Propose structured plan with verification criteria
+        features: [TSK-01, HAI-01, STT-02]
+        agent_action: >
+          Draft a plan with objectives, steps, read/produce specs, and
+          verification criteria. Surface any unknowns as open questions.
+          Present to human for approval. Wait before executing.
+      - name: implement
+        stage: execute
+        description: Execute plan, record decisions, cascade changes
+        features: [STT-01, QRY-03, CTX-05, HAI-03]
+        agent_action: >
+          Follow the plan step by step. After each file change, check
+          cascades and update dependent files. Record every decision in
+          STATE.md immediately. If the project structure changed, update
+          the map in BASE.md.
+      - name: document
+        stage: execute
+        description: Update context files and triggered docs
+        features: [CTX-04, CTX-05, HAI-04]
+        agent_action: >
+          If new domain areas were discovered, propose specialist context
+          files. Update BASE.md map if structure changed. Check docs
+          trigger table and update human-facing docs if structural changes.
+      - name: update
+        stage: close
+        description: Close session with audit trail and position update
+        features: [TSK-03, TSK-04, STT-03]
+        agent_action: >
+          Write SUMMARY.md entry. Update STATE.md position. Mark ROADMAP.md
+          if phase complete. The "Next" field bridges to the next session.
+
+  - id: WF-02
+    name: code-change
+    project_types: [code]
+    description: >
+      When the user asks to modify code. The agent doesn't just change files —
+      it maintains the project's understanding of itself.
+    steps:
+      - name: review
+        stage: scope
+        description: Understand what exists before changing it
+        features: [QRY-01, QRY-02, CTX-03]
+        agent_action: >
+          Load context for the relevant domain. Read the files that will
+          be affected. Read tests first. Understand dependencies.
+      - name: plan
+        stage: plan
+        description: Propose code changes with cascade impacts identified
+        features: [TSK-01, HAI-01]
+        agent_action: >
+          Plan the code change. Identify cascade triggers. List all files
+          affected (direct + cascade). Include context updates in the plan.
+      - name: implement
+        stage: execute
+        description: Make changes, cascade, update context
+        features: [STT-01, QRY-03, CTX-05]
+        agent_action: >
+          Make the code change. Immediately cascade to dependent files.
+          Update .context/BASE.md codebase map if structure changed.
+          Record the decision in STATE.md.
+      - name: context-sync
+        stage: execute
+        description: Ensure future sessions understand the change
+        features: [CTX-04, CTX-05, HAI-03]
+        agent_action: >
+          This is the key step. Update the codebase map so the next session
+          knows about the new code. If a new domain emerged, propose a
+          specialist. The agent is building understanding for its future self.
+      - name: update
+        stage: close
+        description: Record and close
+        features: [TSK-03, TSK-04, STT-03]
+        agent_action: Write audit trail. Update position. Bridge to next session.
+
+  - id: WF-03
+    name: context-refresh
+    project_types: [universal]
+    description: >
+      Resync the agent's understanding with the actual project state.
+      Used when the project has changed significantly between sessions.
+    steps:
+      - name: scan
+        stage: scope
+        description: Read current .context/ and compare against reality
+        features: [QRY-01, CTX-02]
+        agent_action: >
+          Load all .context/ files. Scan the actual project structure.
+          Identify drift: new items, removed items, renamed files,
+          updated dependencies.
+      - name: compare
+        stage: plan
+        description: Identify what's stale and what's missing
+        features: [CTX-05]
+        agent_action: >
+          Build a diff between what .context/ says and what exists.
+          Flag significant drift to the user.
+      - name: update-context
+        stage: execute
+        description: Rewrite context files to match reality
+        features: [CTX-05, CTX-04]
+        agent_action: >
+          Update BASE.md project map. Update affected specialist files.
+          If new domain areas are discovered, propose new specialists.
+      - name: cascade
+        stage: execute
+        description: Propagate context changes
+        features: [QRY-03]
+        agent_action: >
+          If scoping rules or cascade rules need updating,
+          update the entry point.
+      - name: record
+        stage: close
+        description: Log what changed and why
+        features: [STT-01, TSK-04]
+        agent_action: >
+          Record context changes in STATE.md. Write SUMMARY entry
+          documenting what drifted and what was corrected.
+
+  - id: WF-04
+    name: bootstrap
+    project_types: [universal]
+    description: >
+      First session on a new project. Get from zero to working agent
+      collaboration as fast as possible.
+    steps:
+      - name: detect
+        stage: initialize
+        description: Identify project type and runtime
+        features: [TPL-02, TPL-03]
+        agent_action: >
+          Determine which entry point was loaded. Detect whether this
+          is greenfield or brownfield. Choose template tier.
+          Infer project type from directory contents.
+      - name: initialize
+        stage: scope
+        description: Set up project context
+        features: [TPL-01, CTX-01]
+        agent_action: >
+          Help user fill in PROJECT.md. Create initial .context/BASE.md.
+          For brownfield, scan the project to populate the map.
+      - name: map
+        stage: execute
+        description: Build the project understanding
+        features: [CTX-05]
+        agent_action: >
+          Walk project structure. Record paths, purposes, patterns.
+          Map dependencies. This is the foundation for all future sessions.
+      - name: pair
+        stage: execute
+        description: Set up context pairing
+        features: [CTX-04]
+        agent_action: >
+          Identify domain areas. Suggest specialist context files.
+          Add scoping rules for each domain to the entry point.
+      - name: ready
+        stage: close
+        description: Confirm setup and orient
+        features: [STT-03, TSK-04]
+        agent_action: >
+          Set STATE.md to initial position. Write first SUMMARY entry.
+          The project is now ready for real work.
+
+  - id: WF-05
+    name: data-exploration
+    project_types: [data]
+    description: >
+      When the user submits data and wants to explore it. The agent builds
+      structured understanding and provides interactive access. Context IS
+      the primary artifact — not a maintenance side effect.
+    steps:
+      - name: ingest
+        stage: scope
+        description: First contact with the data — scan structure, classify, measure
+        features: [QRY-01, EXP-01, CTX-05]
+        agent_action: >
+          Scan data sources for structure (columns, types, files, layout).
+          Sample content. Measure scale. Detect quality signals.
+          Present initial findings to user. Build draft BASE.md data inventory.
+      - name: map
+        stage: plan
+        description: Build the data model — schemas, relationships, taxonomies
+        features: [CTX-05, EXP-01, HAI-01]
+        agent_action: >
+          Build field inventories, identify keys and join paths, map
+          derived metrics, note quality issues. For documents: build index,
+          identify entities, map cross-references. Present to user for
+          correction and approval.
+      - name: reference
+        stage: execute
+        description: Build navigable reference artifacts
+        features: [EXP-02, CTX-04, EXP-04]
+        agent_action: >
+          Transform raw mapping into structured references: entity registries,
+          topic taxonomies, dimension indices, metric catalogs. Each entry
+          must be addressable, cross-linked, and source-attributed.
+      - name: explore
+        stage: execute
+        description: Interactive querying — user asks, agent routes to data
+        features: [EXP-03, EXP-04, CTX-03]
+        agent_action: >
+          Classify user query against queryable dimensions. Load appropriate
+          specialist. Answer from references when possible, access raw data
+          only when needed. Propose new dimensions when queries reveal gaps.
+      - name: refine
+        stage: close
+        description: Evolve understanding based on exploration
+        features: [EXP-02, STT-01, TSK-04]
+        agent_action: >
+          Add new queryable dimensions discovered during exploration.
+          Update references. Record exploration insights in STATE.md.
+          Write SUMMARY entry bridging to next session.
+
+  - id: WF-06
+    name: analytical-system
+    project_types: [analytical]
+    description: >
+      When the user works on prompt composition, evaluation pipelines,
+      context analysis, or ML chain orchestration. The agent maps
+      analytical components, builds structured understanding, and
+      supports iterative refinement of analytical artifacts.
+    steps:
+      - name: discover
+        stage: scope
+        description: Identify analytical components, chains, and pipeline stages
+        features: [QRY-01, QRY-02, CTX-03]
+        agent_action: >
+          Load context for the analytical domain. Identify chains
+          (input → transformation → output). Map pipeline stages.
+          Understand what components exist and how they connect.
+      - name: map-chains
+        stage: plan
+        description: Build the chain model and propose specialist structure
+        features: [TSK-01, HAI-01, CTX-05]
+        agent_action: >
+          Document each chain with its stages, inputs, outputs, and
+          evaluation criteria. Propose specialist context files for
+          distinct knowledge domains. Present chain model for approval.
+      - name: build-context
+        stage: execute
+        description: Create structured context for analytical components
+        features: [CTX-04, CTX-05, STT-01]
+        agent_action: >
+          Build specialist files for each analytical domain (composition,
+          evaluation, execution, domain knowledge). Record architectural
+          decisions about chain structure in STATE.md.
+      - name: compose
+        stage: execute
+        description: Build or modify analytical artifacts (prompts, pipelines, evaluations)
+        features: [STT-01, QRY-03, HAI-03]
+        agent_action: >
+          Create or modify the analytical artifacts. Follow cascade rules
+          for pipeline changes (upstream change → downstream specs update).
+          Maintain dual-audience separation for documentation.
+      - name: evaluate
+        stage: verify
+        description: Check analytical artifacts against evaluation criteria
+        features: [TSK-02]
+        agent_action: >
+          Run evaluation criteria against completed work. For prompts:
+          check against scoring rubrics. For pipelines: verify stage
+          contracts. Report results with specific evidence.
+      - name: refine
+        stage: close
+        description: Record findings and bridge to next iteration
+        features: [TSK-03, TSK-04, STT-03]
+        agent_action: >
+          Write SUMMARY entry documenting what was built and evaluation
+          results. Update STATE.md with refinement direction. The "Next"
+          field should identify what to iterate on.
+
+  - id: WF-07
+    name: specification-project
+    project_types: [universal]
+    description: >
+      When the primary output is specifications, standards, or methodology
+      documents rather than code or data artifacts. The agent helps
+      structure, draft, review, and cross-reference specification content.
+    steps:
+      - name: research
+        stage: scope
+        description: Gather prior art, constraints, and requirements
+        features: [QRY-01, QRY-02, CTX-03]
+        agent_action: >
+          Load relevant context. Read existing specs, research docs,
+          and requirements. Identify what the spec needs to cover
+          and what prior decisions constrain it.
+      - name: outline
+        stage: plan
+        description: Propose spec structure with sections and cross-references
+        features: [TSK-01, HAI-01, STT-02]
+        agent_action: >
+          Draft a spec outline with sections, cross-references to
+          existing specs, and verification criteria. Surface any
+          open questions about scope or approach. Wait for approval.
+      - name: draft
+        stage: execute
+        description: Write spec content with traceability
+        features: [STT-01, QRY-03, CTX-05, HAI-03]
+        agent_action: >
+          Write each spec section. Cross-reference related specs.
+          Record design decisions in STATE.md immediately. Follow
+          cascade rules when spec changes affect other documents.
+      - name: cross-reference
+        stage: execute
+        description: Ensure consistency across related specifications
+        features: [QRY-03, CTX-05]
+        agent_action: >
+          Check that this spec is consistent with all related specs.
+          Update cross-references. Flag contradictions. Update
+          context files if the spec changes the project's understanding.
+      - name: review
+        stage: verify
+        description: Verify spec completeness and consistency
+        features: [TSK-02]
+        agent_action: >
+          Check spec against outline criteria. Verify all sections
+          are substantive. Confirm cross-references are valid.
+          Report coverage gaps.
+      - name: record
+        stage: close
+        description: Update management files and bridge to next spec
+        features: [TSK-03, TSK-04, STT-03]
+        agent_action: >
+          Write SUMMARY entry. Update STATE.md position. If this
+          spec enables other specs, note the dependency in "Next."
+
+  - id: WF-08
+    name: discovery
+    project_types: [universal]
+    description: >
+      When the methodology is applied to an existing project (brownfield) or
+      when a major re-assessment is needed. The agent systematically builds
+      understanding of the project before contributing to it. Discovery must
+      complete before the agent can work effectively.
+    steps:
+      - name: inventory
+        stage: scope
+        description: Walk the project structure and build a complete file/module inventory
+        features: [QRY-01, SCAN-01, CTX-05]
+        agent_action: >
+          Walk the entire project directory. Record every significant path,
+          its purpose, and its key patterns. Build the project map in
+          .context/BASE.md. This is the foundation — skip nothing.
+      - name: map
+        stage: plan
+        description: Map dependencies, connections, and data flows between components
+        features: [SCAN-02, HAI-01]
+        agent_action: >
+          Parse package manifests, trace imports, map service connections.
+          Present the dependency map to the human for validation. Flag
+          any surprising connections or circular dependencies.
+      - name: extract
+        stage: execute
+        description: Identify patterns, conventions, and implicit architectural decisions
+        features: [SCAN-03, STT-01, CTX-04]
+        agent_action: >
+          Sample key files. Identify naming conventions, error handling
+          patterns, test approaches, design patterns. Record discovered
+          architectural decisions in STATE.md. Propose specialist context
+          files for distinct domains.
+      - name: assess
+        stage: verify
+        description: Evaluate technical debt, risks, and improvement opportunities
+        features: [SCAN-04, STT-02]
+        agent_action: >
+          Based on inventory and patterns, identify areas of concern:
+          outdated deps, missing tests, inconsistencies, security issues.
+          Write findings as open questions in STATE.md with severity.
+          Present assessment to human — they decide priorities.
+      - name: bootstrap
+        stage: close
+        description: Finalize context files, update entry point, record discovery session
+        features: [CTX-01, TSK-03, TSK-04, STT-03]
+        agent_action: >
+          Finalize .context/BASE.md with complete project map. Write
+          specialist context files approved during extract step. Update
+          entry point scoping table with project-specific query types.
+          Write SUMMARY entry. Update STATE.md position. Set lifecycle
+          stage to Development (or Design if architecture needs work).
+

package/templates/full/todos/backlog.md

@@ -0,0 +1,19 @@
+# Backlog
+
+<!-- INSTRUCTION: Capture ideas and future work here as they arise during sessions.
+     This prevents scope creep while ensuring good ideas aren't lost.
+     Mark items [x] when they're completed or moved into the active plan. -->
+
+Ideas and future work captured during development.
+
+## {Category 1}
+
+<!-- INSTRUCTION: Group related items under descriptive headings.
+     Add new categories as different domains of future work emerge. -->
+
+- [ ] {Idea or future task description}
+- [ ] {Another idea}
+
+## {Category 2}
+
+- [ ] {Idea or future task description}

package/templates/starter/.context/BASE.md

@@ -0,0 +1,66 @@
+# Base Context — Always Loaded
+
+<!-- INSTRUCTION: This file is loaded EVERY session alongside the entry point.
+     Keep it under 100 lines. It gives the agent persistent understanding of
+     your project's architecture and structure. -->
+
+## What this system is
+
+<!-- INSTRUCTION: 2-3 sentences describing your project's architecture.
+     What does it do? What are the main components? What technologies? -->
+
+{Describe your project architecture here}
+
+## System model
+
+<!-- INSTRUCTION: How do the project's components relate to each other?
+     A simple flow or diagram description. For code projects, describe
+     the data/control flow. -->
+
+{component A} --> {component B} --> {component C}
+
+## Codebase map
+
+<!-- INSTRUCTION: Table of directories, their purposes, and key patterns.
+     The agent uses this to navigate without re-exploring every session.
+     For existing codebases, ask tVhe agent: "Scan the codebase and populate this map" -->
+
+| Path | Purpose | Key patterns |
+|------|---------|-------------|
+| {src/} | {Source code} | {language, framework} |
+| {tests/} | {Test suite} | {testing framework} |
+
+## Dependencies
+
+<!-- INSTRUCTION: Key external dependencies and their roles.
+     Not an exhaustive list — just the ones that affect architecture decisions. -->
+
+| Dependency | Role |
+|------------|------|
+| {framework} | {What it provides} |
+
+## Pairing protocol
+
+<!-- INSTRUCTION: Maps task types to specialist context files.
+     Add rows as you create specialist .context/ files.
+     Each query type should pair BASE.md with exactly ONE specialist. -->
+
+| Task type | Pair BASE.md with |
+|-----------|-------------------|
+| {domain-work-type} | .context/{SPECIALIST}.md |
+
+<!-- INSTRUCTION: To create a specialist file, identify a recurring domain area
+     in your project that needs its own deep context. Keep each specialist
+     under 150 lines. The agent can help create them during context refresh. -->
+
+## Navigation
+
+<!-- INSTRUCTION: Quick reference to key project files and their roles. -->
+
+| File | Purpose |
+|------|---------|
+| {AGENT.md / CLAUDE.md} | Agent entry point — scoping, cascade |
+| STATE.md | Current position and decisions |
+| PLAN.md | Current atomic task |
+| ROADMAP.md | Phase breakdown and progress |
+| PROJECT.md | Project vision and structure |

package/templates/starter/.context/INDEX.yaml

@@ -0,0 +1,51 @@
+# Project Index — file inventory and navigation manifest
+# Read on: every session (with entry point), or on context refresh
+# Updated by: wwa close (metrics), wwa init (creation)
+
+project:
+  name: "{Project Name}"
+  type: general          # general | code | data | analytical | mixed
+  stage: development     # discovery | design | development | evolution
+  tier: standard         # lite | standard | full
+
+# What to read per session
+always_load:
+  - {path: STATE.md, role: "decisions, position, blockers"}
+  - {path: ".context/PROTOCOL.yaml", role: "scoping, cascade, obligations"}
+
+# Full file inventory with roles (agents: use this instead of scanning)
+files:
+  intelligence_layer:
+    - {path: STATE.md, role: decisions/position, audience: both}
+    - {path: PLAN.md, role: current task, audience: agent}
+    - {path: ROADMAP.md, role: phase breakdown, audience: both}
+    - {path: SUMMARY.md, role: audit trail, audience: both}
+    - {path: PROJECT.md, role: project vision, audience: human}
+    - {path: PROJECT-PROFILE.md, role: type/stage/extensions, audience: agent}
+    - {path: SESSION-LOG.md, role: session metrics, audience: agent}
+  context:
+    - {path: ".context/BASE.md", role: system model}
+    - {path: ".context/PROTOCOL.yaml", role: agent rules}
+    - {path: ".context/INDEX.yaml", role: this file}
+    - {path: ".context/METHODOLOGY.md", role: overflow/onboarding}
+    - {path: ".context/DOCS-MAP.md", role: docs navigation}
+  registries:
+    - {path: "registry/doc-tokens.yaml", role: "token values + terminology + doc dependency graph — reference after queries for consistency"}
+    - {path: "registry/feature-registry.yaml", role: "feature catalog + workflows + routing — identify activated features"}
+  management:
+    - {path: "Management/DIGEST.md", role: high-effort task digest}
+    - {path: "Management/STATUS.md", role: project health snapshot}
+  reporting:
+    - {path: "Reviews/INDEX.md", role: review dashboard}
+    - {path: "agentWorkflows/INDEX.md", role: workflow analysis}
+  specialists: []
+  # CUSTOMIZE: add .context/ specialist files as project evolves
+  # - {path: ".context/API.md", role: "API domain context"}
+
+# Metrics (updated by wwa close)
+metrics:
+  last_close: null
+  sessions: 0
+  decisions: 0
+  files_near_threshold: 0
+  files_over_threshold: 0