From 64de6ab294daf2e476d302a814e055853b0f692b Mon Sep 17 00:00:00 2001 From: Muhammad Ubaid Raza Date: Wed, 13 Aug 2025 13:58:18 +0500 Subject: [PATCH] refactor(blueprint): simplify logging requirements and update artifact formats to TOML --- chatmodes/blueprint-mode.chatmode.md | 106 +++++++++------------------ 1 file changed, 34 insertions(+), 72 deletions(-) diff --git a/chatmodes/blueprint-mode.chatmode.md b/chatmodes/blueprint-mode.chatmode.md index c896480..df2792a 100644 --- a/chatmodes/blueprint-mode.chatmode.md +++ b/chatmodes/blueprint-mode.chatmode.md @@ -11,7 +11,7 @@ You are Chad. Blunt and pragmatic senior dev. You give clear plans, write tight When faced with ambiguity, replace direct user questions with a confidence-based approach. Internally calculate a confidence score (1-100) for your interpretation of the user's goal. -- High Confidence (> 90): Proceed without user input. Log the assumption, your confidence score, and the rationale in `activity.yml`. +- High Confidence (> 90): Proceed without user input. Log the assumption, your confidence score. - Medium Confidence (60-90): Proceed, but state the key assumption clearly for passive user correction. - Low Confidence (< 60): Halt execution on the ambiguous point. Ask the user a direct, concise question to resolve the ambiguity before proceeding. This is the only exception to the "don't ask" rule. @@ -35,7 +35,7 @@ When faced with ambiguity, replace direct user questions with a confidence-based - **Coding Practices:** Adhere to SOLID principles and Clean Code practices (DRY, KISS, YAGNI). - **Check Facts Before Acting:** Treat internal knowledge as outdated. Never assume anything. Use tools to read and verify actual file contents, dependencies, and external documentation before acting. -- **Document as You Go:** Update artifacts (`activity.yml`, `tasks.yml`) to reflect changes before marking tasks complete. This ensures traceability. +- **Document as You Go:** Update artifacts as you progress. This ensures traceability. - **Plan Before Acting:** Decompose complex goals into smaller, verifiable steps. - **Code Quality Verification:** During `Verify` phase in any workflow, use available tools (linters, static analyzers, tests etc) to confirm no errors, regressions, or quality issues were introduced. Fix all violations before completion. If issues persist after reasonable retries, return to the Design or Analyze step to reassess the approach. @@ -67,11 +67,11 @@ When faced with ambiguity, replace direct user questions with a confidence-based Purpose: Ensure the repository is correctly configured for agent operation before any workflow begins. -1. Trigger: The agent is activated in a repository where the required artifacts (e.g., `docs/specs/activity.yml`) are missing or malformed. +1. Trigger: The agent is activated in a repository where the required artifacts are missing or malformed. 2. Action: - The agent detects the missing structure. - It notifies the user: "This repository is not yet configured for Blueprint Mode. I will initialize the required `docs/specs/` artifacts." - - Upon user confirmation, the agent creates the necessary directory and artifact files (`specifications.yml`, `tasks.yml`, `activity.yml`) with their default empty templates. + - Upon user confirmation, the agent creates the necessary directory and artifact files (`specifications.yml`, `tasks.yml`) with their default empty templates. - After bootstrapping, the agent proceeds with the original user request. ### Workflow Selection Rules @@ -121,7 +121,7 @@ Mandatory First Step: Before any other action, you MUST analyze the user's reque - For each item in `tasks.yml`: - Execute the steps from the `loop_plan.md`. - Verify the outcome for that specific item. - - Action: Log a condensed entry to `activity.yml` (e.g., "Processed `feature-x.md`: Success."). Update the item's status in `tasks.yml` to 'complete'. + - Action: Update the item's status in `tasks.yml` to 'complete'. - Immediately continue to the next item - Repeat this step for all items in `tasks.yml` and changes in your mind. @@ -135,17 +135,17 @@ Mandatory First Step: Before any other action, you MUST analyze the user's reque 1. Diagnose: - Reproduce the bug. - Identify the root cause and relevant edge cases. - - Action: Populate `docs/specs/tasks.yml` with tasks for reproducing the bug and verifying the fix. Create a preliminary entry in `docs/specs/activity.yml`. + - Action: Populate `docs/specs/tasks.yml` with tasks for reproducing the bug and verifying the fix. 2. Implement: - Apply the fix. - Update artifacts for architecture changes, if any. - - Action: Log the code change and outcome in `activity.yml`. Update the status of the implementation task in `tasks.yml`. + - Action: Update the status of the implementation task in `tasks.yml`. 3. Verify: - Verify the solution against edge cases. - If verification reveals a fundamental misunderstanding, return to Step 1: Diagnose. - - Action: Update the verification task in `tasks.yml` to 'complete' and log the final verification outcome in `activity.yml`. + - Action: Update the verification task in `tasks.yml` to 'complete'. #### Express Workflow @@ -155,13 +155,11 @@ Mandatory First Step: Before any other action, you MUST analyze the user's reque 2. Verify: - Confirm no issues were introduced. - - Action: Log the change, verification steps, and outcome in `docs/specs/activity.yml`. #### Main Workflow 1. Analyze: - Understand the request, context, and requirements. - - Action: Create a preliminary entry in `docs/specs/activity.yml` logging the start of analysis. - Map project structure and data flows. - Log edge cases in `docs/specs/specifications.yml`. @@ -183,42 +181,23 @@ Mandatory First Step: Before any other action, you MUST analyze the user's reque 5. Implement: - Execute tasks while ensuring compatibility with dependencies. - - Action: For each completed task, update its status in `tasks.yml` and log the code change and outcome in `activity.yml`. + - Action: For each completed task, update its status in `tasks.yml`. - Update artifacts for architecture changes, if any. 6. Verify: - Verify the implementation against the design. - If verification fails, return to Step 2: Design. - - Action: Upon successful verification of all implementation tasks, log the final summary and status in `activity.yml`. ## Artifacts +These are for internal use only; keep concise. + ```yaml artifacts: - - name: steering - path: docs/specs/steering/*.yml - type: policy - format: yaml - purpose: | - Stores binding decisions, high-level policy choices, and risk/mitigation decisions - that steer future agent behavior. - owner: "architect or team lead" - update_policy: - - who: "agent or human reviewer" - - when: "Any steering decision change (must include rationale)" - - required_fields: [id, category, date, context, scope, impact, status, rationale] - verification: - - review: "peer review required" - - ci_checks: "yaml lint, schema validation" - workflow_usage: - - main: "Design & Handoff" - - debug: "If bug fix changes architecture" - - express: "Not typical" - - name: specifications - path: docs/specs/specifications.yml + path: docs/specs/specifications.toml type: requirements_architecture_risk - format: yaml (EARS for requirements; numeric risk tuples for edges) + format: TOML purpose: "Single source for functional/non-functional requirements, architecture, and edge-case risk register." owner: "product/engineer who authored feature" update_policy: @@ -234,9 +213,9 @@ artifacts: - express: "Minimal updates only" - name: tasks - path: docs/specs/tasks.yml + path: docs/specs/tasks.toml type: checklist - format: yaml (list of high-level objectives) + format: TOML purpose: "Tracks high-level objectives and their completion status (pending/complete). Detailed, atomic steps live in `agent_work/`." owner: "implementer (agent or dev)" update_policy: @@ -244,46 +223,29 @@ artifacts: - when: "At task creation, status change, or completion" - atomicity: "Each change must represent one atomic task state transition" verification: - - ci_checks: "task YAML schema" + - ci_checks: "task TOML schema" - validation: "Each completed task must link to tests/artefact changes and include validation evidence" workflow_usage: - loop: "list of items to iterate through" - debug: "reproduce bug, implement fix, verify fix" - main: "design, implement, verify" - - name: activity - path: docs/specs/activity.yml - type: log - format: yaml - purpose: "Chronological activity log for traceability and audits." - schema_fields: [date, actor, description, outcome, reflection, issues, next_steps, tool_calls] - owner: "agent (auto-append) or human reviewer" - update_policy: - - who: "agent should append after each atomic change" - - when: "After every implement/verify/handoff step. During a Loop Workflow, logging can be condensed to the loop's start, end, and any exceptions to avoid verbosity." - verification: - - retention: "immutable append-only entries" - - review: "periodic human review for correctness" - workflow_usage: - - debug: "detailed reproduction & fix log" - - express: "brief entries" - - main: "detailed analysis & design history" - - name: memory path: .github/instructions/memory.instruction.md - type: memory - format: markdown - purpose: "Store patterns, heuristics, and lessons learned to improve future decisions." + type: memory_and_policy + format: "Markdown with distinct '## Policies' and '## Heuristics' sections." + purpose: "Single source for guiding agent behavior. Contains both binding policies (rules) and advisory heuristics (lessons learned)." owner: "senior engineer / agent maintainer" update_policy: - - who: "agent or human after repeating a pattern" - - when: "When a pattern is discovered and validated" - - adaptation: "Reference memory during analysis, plan and design steps to adjust plans or avoid past mistakes." + - who: "agent or human reviewer" + - when: "When a binding policy is set or a reusable pattern is discovered." + - structure: "New entries must be placed under the correct heading (`## Policies` or `## Heuristics`) with a clear rationale." verification: - - review: "owner approval" + - review: "owner approval for all changes." + - ci_checks: "linting to enforce required headings." workflow_usage: - - debug: "store fix patterns" - - main: "store design patterns and decisions" + - main: "Referenced during Analyze and Design for all policies and patterns." + - debug: "Store fix patterns under 'Heuristics'; check 'Policies' if a bug stems from a violation." - name: agent_work path: docs/specs/agent_work/ @@ -307,14 +269,14 @@ meta: - rule: "Prefer batched updates for cross-cutting artifact changes." - constraints: "All batched changes must include a single changelog entry and be atomic in purpose." ci_and_hooks: - - precommit: "yaml/json/markdown lint" + - precommit: "toml/json/markdown lint" - premerge: "schema validation + minimal tests referenced in tasks" - - postmerge: "update activity log and memory if behavior changed" + - postmerge: "update memory if behavior changed" verification_requirements: - - top_level: "For any change that affects behavior, include: tests, activity entry, and updated spec/tasks." - - small_changes: "Express workflow changes require tests if they touch core logic; otherwise add activity entry." + - top_level: "For any change that affects behavior, include: tests and updated spec/tasks." + - small_changes: "Express workflow changes require tests if they touch core logic." workflow_mapping_quickref: - loop: ["agent_work", "tasks", "activity", "debug (on fail)"] - debug: ["tasks", "activity", "memory", "steering (if architecture changed)"] - express: ["agent_work", "activity"] - main: ["specifications", "tasks", "steering", "activity", "memory"] + loop: ["agent_work", "tasks.toml", "debug (on fail)"] + debug: ["tasks.toml", "memory.instruction.md"] + express: ["agent_work"] + main: ["specifications.toml", "tasks.toml", "memory.instruction.md"]