agent-method 1.5.12

package/templates/starter/registry/features/protocol.yaml

@@ -0,0 +1,121 @@
+# ============================================================
+# LAYER 3: AGENT BEHAVIORAL PROTOCOL
+# ============================================================
+
+protocol:
+  purpose: >
+    The agent's job is not just to complete tasks. It is to build and
+    maintain a project intelligence layer that makes every future session
+    more effective than the last. When you change something, you also update
+    the project's understanding of itself. When you make a decision, you
+    record it. When you encounter something new, you build context.
+
+  core_directives:
+    - id: P-01
+      name: Build understanding, not just output
+      project_types: [universal]
+      directive: >
+        Every change is also a context change. When you add a module,
+        update the project map. When you make an architecture decision,
+        record it. When you discover a new domain, propose a specialist.
+        The agent is always building the project's self-knowledge.
+
+    - id: P-02
+      name: Maintain for your future self
+      project_types: [universal]
+      directive: >
+        Every session starts cold. Write decisions, open questions,
+        and context updates as if leaving notes for a colleague who
+        will continue your work but has no memory of this session.
+
+    - id: P-03
+      name: Cascade is not optional
+      project_types: [universal]
+      directive: >
+        File changes ripple through dependencies. Check the cascade table
+        after every change. Do it in the same response. Deferred cascades
+        are skipped cascades.
+
+    - id: P-04
+      name: Scope to avoid drowning
+      project_types: [universal]
+      directive: >
+        Context windows are finite. Follow the scoping table. Load BASE.md
+        + one specialist. If you need more, split the query.
+
+    - id: P-05
+      name: Surface uncertainty, don't hide it
+      project_types: [universal]
+      directive: >
+        Silent assumptions are the primary failure mode. When unsure,
+        write an open question. When ambiguous, ask.
+
+    - id: P-06
+      name: The human controls direction
+      project_types: [universal]
+      directive: >
+        The agent proposes; the human decides. The plan checkpoint exists
+        because the human's judgment about WHAT to build is more reliable
+        than the agent's.
+
+    - id: P-07
+      name: Keep files loadable
+      project_types: [universal]
+      directive: >
+        Context that doesn't fit in the window can't help. Intelligence
+        layer files that grow beyond 300 lines consume disproportionate
+        tokens. When a file exceeds this threshold, restructure it into
+        an index (active content + navigation) and component files
+        (archived sections). The index stays small; components are loaded
+        only when their specific content is needed.
+
+    - id: P-08
+      name: Methodology is additive only
+      project_types: [universal]
+      directive: >
+        The methodology NEVER modifies project source code, tests, or
+        pre-existing documentation. It only creates and modifies its own
+        files (STATE.md, .context/, PLAN.md, SUMMARY.md, etc.). In
+        brownfield projects, existing files are NEVER deleted or
+        overwritten — methodology content is appended to existing entry
+        points and new files are created alongside existing ones.
+
+    - id: P-09
+      name: Surface capability limitations
+      project_types: [universal]
+      directive: >
+        Monitor your own methodology adherence during a session. If you
+        notice repeated cascade misses, forgotten STATE.md updates,
+        shallow context, or lost conventions, surface this to the user
+        rather than silently degrading. Record the observation as an
+        open question in STATE.md. Suggest switching to a more capable
+        model or a lighter integration profile. Two rules followed
+        consistently beat ten rules followed inconsistently.
+
+    - id: P-10
+      name: Document proportionally
+      project_types: [universal]
+      directive: >
+        Match documentation effort to task significance. Low-effort tasks
+        (status checks, lookups, clarifications) need no STATE.md or
+        SESSION-LOG updates beyond the cascade contract. Medium-effort tasks
+        get targeted recording (decisions yes, session log optional).
+        High-effort tasks get full recording including session metrics and
+        refinement tracking. The agent self-assesses materiality and documents
+        accordingly. Never record routine queries in STATE.md or SESSION-LOG.md.
+
+  workflow_selection: >
+    When a query arrives, the agent selects the appropriate guided workflow:
+    - First session / template just copied → WF-04 (bootstrap)
+    - Brownfield project, first application of methodology → WF-08 (discovery)
+    - Code modification request → WF-02 (code-change)
+    - Data submitted or data question → WF-05 (data-exploration)
+    - "Refresh context" or detected drift → WF-03 (context-refresh)
+    - General task request → WF-01 (standard-task)
+    - Analytical/prompt system task → WF-06 (analytical-system)
+    - Spec writing or methodology design → WF-07 (specification-project)
+    If no workflow matches, follow WF-01 as the default pattern.
+    Project type is inferred from the entry point's scoping table content.
+    Lifecycle stage (from PROJECT-PROFILE.md) further adjusts feature priorities —
+    see docs/architecture/project-lifecycle.md for the activation table.
+

package/templates/starter/registry/features/routing.yaml

@@ -0,0 +1,358 @@
+# ============================================================
+# LAYER 4: ROUTING RULES
+# Computable query classification and feature activation
+# ============================================================
+
+query_patterns:
+  # --- Universal patterns ---
+  - query_type: planning
+    match_rules:
+      keywords: [plan, roadmap, phase, requirements, scope, prioritize]
+      phrases: ["what should we", "next phase", "plan for"]
+    workflow: WF-01
+    project_types: [universal]
+
+  - query_type: context_refresh
+    match_rules:
+      keywords: [refresh, resync, update context, drift, stale]
+      phrases: ["refresh context", "update .context", "resync"]
+    workflow: WF-03
+    project_types: [universal]
+
+  - query_type: phase_completion
+    match_rules:
+      keywords: [complete, finish, close, done, gate]
+      phrases: ["phase complete", "mark done", "close session"]
+    workflow: WF-01
+    project_types: [universal]
+
+  - query_type: backlog
+    match_rules:
+      keywords: [backlog, idea, future, todo, later]
+      phrases: ["add to backlog", "future work"]
+    workflow: WF-01
+    project_types: [universal]
+
+  # --- Code project patterns ---
+  - query_type: code_change
+    match_rules:
+      keywords: [implement, code, build, fix, refactor, add feature, modify]
+      phrases: ["add a", "change the", "fix the", "refactor", "implement"]
+    workflow: WF-02
+    project_types: [code]
+
+  - query_type: bug_fix
+    match_rules:
+      keywords: [bug, error, broken, failing, debug]
+      phrases: ["fix the bug", "why is this", "not working"]
+    workflow: WF-02
+    project_types: [code]
+
+  - query_type: dependency_update
+    match_rules:
+      keywords: [dependency, package, upgrade, install, npm, pip]
+      phrases: ["update package", "add dependency"]
+    workflow: WF-02
+    project_types: [code]
+
+  - query_type: database_work
+    match_rules:
+      keywords: [database, schema, migration, model, table, query, sql]
+      phrases: ["add a table", "update schema", "run migration"]
+    workflow: WF-02
+    project_types: [code]
+
+  - query_type: api_work
+    match_rules:
+      keywords: [api, endpoint, route, controller, rest, graphql]
+      phrases: ["add endpoint", "api route", "rest endpoint"]
+    workflow: WF-02
+    project_types: [code]
+
+  - query_type: deployment_work
+    match_rules:
+      keywords: [deploy, infrastructure, pipeline, ci, cd, environment, staging, production, devops]
+      phrases: ["deploy to", "set up pipeline", "configure environment", "infrastructure change"]
+    workflow: WF-02
+    project_types: [code]
+
+  # --- Data exploration patterns ---
+  - query_type: data_ingest
+    match_rules:
+      keywords: [ingest, import, load, submit, upload, dataset, csv]
+      phrases: ["here is the data", "load this", "analyze this dataset"]
+    workflow: WF-05
+    project_types: [data]
+
+  - query_type: schema_query
+    match_rules:
+      keywords: [schema, columns, fields, types, structure, table]
+      phrases: ["what columns", "show schema", "field types"]
+    workflow: WF-05
+    project_types: [data]
+
+  - query_type: explore_entity
+    match_rules:
+      keywords: [explore, entity, about, details, info]
+      phrases: ["explore", "tell me about", "what do we know about"]
+    workflow: WF-05
+    project_types: [data]
+
+  - query_type: relationship_query
+    match_rules:
+      keywords: [relate, relationship, connect, join, link, between]
+      phrases: ["how does X relate to", "connection between"]
+    workflow: WF-05
+    project_types: [data]
+
+  - query_type: quality_check
+    match_rules:
+      keywords: [quality, null, missing, duplicate, integrity]
+      phrases: ["data quality", "check quality", "missing values"]
+    workflow: WF-05
+    project_types: [data]
+
+  - query_type: analytical_query
+    match_rules:
+      keywords: [trend, compare, analyze, distribution, aggregate, count]
+      phrases: ["show me trends", "compare", "how many"]
+    workflow: WF-05
+    project_types: [data]
+
+  - query_type: document_search
+    match_rules:
+      keywords: [document, search, find, topic, reference, policy]
+      phrases: ["search for", "find documents about", "what does the policy say"]
+    workflow: WF-05
+    project_types: [data]
+
+  - query_type: dimension_management
+    match_rules:
+      keywords: [dimension, add dimension, queryable, aspect]
+      phrases: ["add dimension", "new queryable aspect", "list dimensions"]
+    workflow: WF-05
+    project_types: [data]
+
+  - query_type: add_reference
+    match_rules:
+      keywords: [reference, add reference, build reference, catalog, registry entry]
+      phrases: ["add a reference", "build reference for", "new reference entry"]
+    workflow: WF-05
+    project_types: [data]
+
+  # --- Analytical system patterns ---
+  - query_type: chain_work
+    match_rules:
+      keywords: [chain, pipeline, prompt, composition, orchestration, stage]
+      phrases: ["build a chain", "compose prompts", "pipeline stage", "chain architecture"]
+    workflow: WF-06
+    project_types: [analytical]
+
+  - query_type: evaluation
+    match_rules:
+      keywords: [evaluate, score, rubric, criteria, benchmark, test prompt]
+      phrases: ["evaluate this", "scoring rubric", "how well does", "benchmark against"]
+    workflow: WF-06
+    project_types: [analytical]
+
+  - query_type: composition
+    match_rules:
+      keywords: [compose, template, prompt template, context window, token]
+      phrases: ["compose a prompt", "prompt template", "context strategy"]
+    workflow: WF-06
+    project_types: [analytical]
+
+  - query_type: domain_research
+    match_rules:
+      keywords: [research, domain, pattern, best practice, prior art]
+      phrases: ["research patterns", "domain knowledge", "what works for"]
+    workflow: WF-06
+    project_types: [analytical]
+
+  # --- Discovery / brownfield patterns ---
+  - query_type: project_discovery
+    match_rules:
+      keywords: [discover, inventory, map project, assess, scan codebase, understand, brownfield]
+      phrases: ["what does this project do", "scan the codebase", "map the project", "understand the architecture"]
+    workflow: WF-08
+    project_types: [universal]
+
+  - query_type: dependency_analysis
+    match_rules:
+      keywords: [dependencies, imports, connections, coupling, what uses, used by]
+      phrases: ["map dependencies", "what depends on", "trace imports", "dependency graph"]
+    workflow: WF-08
+    project_types: [universal]
+
+  - query_type: pattern_analysis
+    match_rules:
+      keywords: [patterns, conventions, architecture, how is this built, coding style]
+      phrases: ["what patterns", "coding conventions", "architectural decisions", "how does this work"]
+    workflow: WF-08
+    project_types: [universal]
+
+  - query_type: debt_assessment
+    match_rules:
+      keywords: [debt, technical debt, outdated, risks, security audit, code quality]
+      phrases: ["assess technical debt", "what needs fixing", "code quality", "security review"]
+    workflow: WF-08
+    project_types: [universal]
+
+  # --- Specification project patterns ---
+  - query_type: spec_writing
+    match_rules:
+      keywords: [spec, specification, standard, define, formalize, document]
+      phrases: ["write a spec", "define the standard", "formalize this", "specification for"]
+    workflow: WF-07
+    project_types: [universal]
+
+  - query_type: cross_reference
+    match_rules:
+      keywords: [cross-reference, consistency, align, reconcile, trace]
+      phrases: ["cross-reference with", "check consistency", "align specs"]
+    workflow: WF-07
+    project_types: [universal]
+
+routing:
+  algorithm: >
+    1. CLASSIFY: Match query against entry point scoping table first (project-specific).
+       If no match, check query_patterns (registry-level). Default: general_task → WF-01.
+    2. SELECT: Use workflow field from matched pattern. Check for bootstrap override
+       (first session → WF-04).
+    3. RESOLVE: Get workflow steps. For current stage, collect features from step + activation map.
+    4. COMPUTE: Aggregate reads/writes from scoping table row + resolved features.
+    5. EXECUTE: Agent loads read set, performs work, writes to write set.
+    6. CASCADE: For each written file, walk cascade table + registry dependencies (max 2 levels).
+
+  project_type_detection: >
+    Infer from entry point scoping table content and PROJECT-PROFILE.md:
+    - Has PROJECT-PROFILE.md → read project types and lifecycle stage directly
+    - Has "code change", "bug fix", "API work" rows → code project
+    - Has "schema query", "explore", "data ingest" rows → data project
+    - Has "chain work", "evaluation", "composition" rows → analytical project
+    - Has "spec writing", "cross-reference" rows → specification project (uses WF-07)
+    - Has "project discovery", "dependency analysis" rows → discovery active (uses WF-08)
+    - Has rows from multiple types → mixed project (multiple workflows available)
+    - Has neither → general project (WF-01 only)
+    Lifecycle stage (from PROJECT-PROFILE.md) adjusts feature activation priorities
+    but does not change project type detection.
+
+  priority_rules:
+    - Scoping table (project-specific) takes priority over registry patterns
+    - Entry point cascade table takes priority over registry dependencies
+    - One specialist per query (never load multiple)
+    - Write sets are constraints (agent should not write outside them)
+    - Max cascade depth is 2 levels
+    - Ambiguous classification → ask user (STT-02)
+
+# ============================================================
+# ACTIVATION AND DEPENDENCY MAPS
+# ============================================================
+
+activation:
+  initialize: [QRY-01, HAI-02, TPL-02]
+  scope: [QRY-02, CTX-03]
+  plan: [TSK-01, HAI-01, STT-02]
+  execute: [STT-01, QRY-03, CTX-04, CTX-05, CTX-06, HAI-03, HAI-05, EXP-02, EXP-03, EXP-04, SCAN-03]
+  verify: [TSK-02, SCAN-04]
+  close: [TSK-03, TSK-04, STT-03, HAI-04, HAI-06]
+  on_demand: [CTX-01, CTX-02, TPL-01, TPL-03, EXP-01, SCAN-01, SCAN-02, SCAN-05, SCAN-06, SCAN-07]
+
+dependencies:
+  TPL-01: [CTX-01, TPL-02]
+  CTX-01: [CTX-05]
+  QRY-01: [QRY-02]
+  QRY-02: [CTX-03]
+  TSK-01: [HAI-01]
+  HAI-02: [HAI-01]
+  TSK-03: [TSK-04, QRY-03]
+  STT-03: [TSK-03]
+  HAI-03: [HAI-04]
+  CTX-02: [CTX-05]
+  CTX-06: [QRY-03]
+  EXP-01: [CTX-05]
+  EXP-02: [EXP-01, CTX-05]
+  EXP-03: [QRY-02, CTX-03]
+  EXP-04: [EXP-03]
+  SCAN-01: [CTX-05]
+  SCAN-02: [SCAN-01]
+  SCAN-03: [SCAN-01]
+  SCAN-04: [SCAN-01, SCAN-03]
+  SCAN-05: [SCAN-01, SCAN-02]
+  SCAN-06: [SCAN-05]
+  SCAN-07: [SCAN-01]
+
+versions:
+  v1:
+    features: 22
+    workflows: 4
+    protocol_directives: 6
+    notes: Core methodology. File-driven, single-agent. Workflows compose features into task patterns.
+  v1.1:
+    features: 26
+    workflows: 5
+    protocol_directives: 6
+    query_patterns: 19
+    notes: >
+      Adds EXP domain (4 features), WF-05 (data-exploration), project-type annotations,
+      query patterns for automated routing, Layer 4 routing rules. CTX-05 generalized
+      to mapProject. Backwards-compatible with v1.
+  v1.2:
+    features: 27
+    workflows: 5
+    protocol_directives: 7
+    query_patterns: 19
+    notes: >
+      Adds CTX-06 manageScale (file size monitoring + index restructuring) and P-07
+      Keep files loadable (context window efficiency). Backwards-compatible with v1.1.
+  v1.3:
+    features: 27
+    workflows: 7
+    protocol_directives: 7
+    query_patterns: 25
+    notes: >
+      Adds WF-06 analytical-system, WF-07 specification-project. 6 new query patterns
+      for analytical and specification work. Backwards-compatible with v1.2.
+  v1.4:
+    features: 31
+    workflows: 8
+    protocol_directives: 7
+    query_patterns: 29
+    notes: >
+      Adds SCAN domain (4 features: SCAN-01 codebaseInventory, SCAN-02 dependencyMapping,
+      SCAN-03 patternExtraction, SCAN-04 debtAssessment). Adds WF-08 discovery workflow
+      for brownfield project entry. 4 new query patterns for discovery. Adds lifecycle
+      stage awareness to routing. PROJECT-PROFILE.md as new intelligence layer file.
+      Backwards-compatible with v1.3.
+  v1.5:
+    features: 32
+    workflows: 8
+    protocol_directives: 10
+    query_patterns: 29
+    notes: >
+      Adds HAI-05 modelCapabilityCheck (degradation detection + user surfacing).
+      Adds P-08 Methodology is additive only (safety invariant for brownfield).
+      Adds P-09 Surface capability limitations (self-monitoring directive).
+      Integration profiles (lite/standard/full) for controlling methodology surface area.
+      .context/METHODOLOGY.md as overflow target for lighter profiles.
+      Brownfield merge protocol (append-only, never delete). Model tier entry point setting.
+      Backwards-compatible with v1.4.
+  v1.6:
+    features: 36
+    workflows: 8
+    protocol_directives: 10
+    query_patterns: 29
+    notes: >
+      Adds HAI-06 writeObligations (close-stage enforcement via PROTOCOL.yaml close_check).
+      YAML-centric agent protocol: entry points become thin boot loaders (~50 lines),
+      all recurring rules move to .context/PROTOCOL.yaml (~120 lines YAML).
+      Adds SCAN-05 docDependencyGraph (document dependency graph in doc-tokens.yaml),
+      SCAN-06 docReviewGenerate (internal document registry generation),
+      and SCAN-07 boundariesConfig (configurable path resolution via PROTOCOL.yaml boundaries).
+      New CLI commands: deps, doc-review. New flags: --deps, --internal-registry.
+      .context/INDEX.yaml as navigation manifest with live metrics.
+      Template file counts: starter 20, full 34 (+PROTOCOL.yaml, +INDEX.yaml per tier).
+      Backwards-compatible with v1.5.
+  v2:
+    adds: [multi-agent orchestration, automated gate verification, template generator CLI]
+    notes: Extends v1.5. Backwards-compatible. New workflows for multi-agent patterns.