agent-method 1.5.12

package/templates/starter/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).
+