diff --git a/playbooks/AI_WORKFLOW_PLAYBOOK.md b/playbooks/AI_WORKFLOW_PLAYBOOK.md index 5c06c94..a727730 100644 --- a/playbooks/AI_WORKFLOW_PLAYBOOK.md +++ b/playbooks/AI_WORKFLOW_PLAYBOOK.md @@ -17,7 +17,7 @@ Date: 2026-02-20 ### 2. Finish Branch **Goal**: Safely finalize a branch before opening a PR, ensuring all tests pass and docs are up-to-date. -Finishing a branch runs a code review (guided by `docs/ai/code_review_prompt.md`), then a compliance and traceability audit against deterministic standards. The AI waits for you to push and paste any CI or BugBot feedback, loops on fixes until CI is green, and only then proceeds to final spackle: running sync-docs to update any docs that need changes based on the branch diff (SPEC, SCHEMA_REFERENCE, DATA_FLOW_MAP, ADRs, etc.), harvesting new rules into architecture docs, ensuring CHANGELOG is updated for user-facing changes, updating `docs/ROADMAP.md` to mark the completed item as done, and outputting the PR description in a code block. The AI never auto-commits or auto-pushes; it provides the exact `git push` command for you to run. +Finishing a branch runs a code review (guided by `docs/ai/code_review_prompt.md`), then a compliance and traceability audit against deterministic standards. The AI waits for you to push and paste any CI or BugBot feedback, loops on fixes until CI is green, and only then proceeds to final spackle: running sync-docs to update any docs that need changes (using both the branch diff and the active task session — session is semantically analyzed so domain, decisions, data semantics, and conventions are pushed to the right docs), harvesting new rules from diff, review_ledger, and task session into architecture docs and .cursorrules, ensuring CHANGELOG is updated for user-facing changes, updating `docs/ROADMAP.md` to mark the completed item as done, and outputting the PR description in a code block. The AI never auto-commits or auto-pushes; it provides the exact `git push` command for you to run. ### 3. Status Check **Goal**: Understand blocking issues and re-hydrate the AI's state. @@ -31,9 +31,9 @@ Finishing a branch runs a code review (guided by `docs/ai/code_review_prompt.md` | code-review | code review, run code review, review my changes | Project-specific static analysis and fix loop | | status-check | status check, where are we, blocked | Rehydrate context and diagnose blockers | | process-feedback | pasting CI logs, Bugbot comments, SonarQube errors | Interrupt subroutine: fix code, log diagnosis to short-term memory, resume previous task | -| harvest-rules | harvest rules, update docs | Extract new patterns into docs and .cursorrules | +| harvest-rules | harvest rules, update docs | Extract new patterns from diff, review_ledger, and task session into docs and .cursorrules | | audit-compliance | audit compliance, run audit | IV&V audit against deterministic standards | -| sync-docs | sync docs, sync project docs | Keep docs in sync with branch changes (SPEC, SCHEMA_REFERENCE, DATA_FLOW_MAP, ADRs, etc.) | +| sync-docs | sync docs, sync project docs | Keep docs in sync with branch diff and task session (semantic analysis → SPEC, SCHEMA_REFERENCE, ADRs, .cursorrules, etc.) | | pr-description | PR description, draft PR | Output PR description in a code block | | roadmap-manage | roadmap, manage roadmap, add to roadmap | Add, prioritize, catalog roadmap items | | roadmap-consult | roadmap status, what's pending, roadmap consult | Read-only view of done/pending/priorities | diff --git a/playbooks/EXPECTED_PROJECT_STRUCTURE.md b/playbooks/EXPECTED_PROJECT_STRUCTURE.md index 9c1f489..5b162cc 100644 --- a/playbooks/EXPECTED_PROJECT_STRUCTURE.md +++ b/playbooks/EXPECTED_PROJECT_STRUCTURE.md @@ -8,10 +8,11 @@ This document lists every referenced path, its purpose, and how it fits into the *Located in `.agenticguild/` (Gitignored)* | Path | Purpose | |------|---------| -| `current_state.md` | Tracks the active skill, phase, and step. Used to resume tasks. Format: `` = session filename (e.g. `task_foo.md`) or `[NONE]`; `` contains ``, ``, ``. | +| `current_state.md` | Tracks the active skill, phase, and step. Used to resume tasks. Format: `` = session filename (e.g. `task_foo.md`) or `[NONE]`; `` contains ``, ``, ``. When multiple session files exist, the active task pointer MUST be set so status-check and cross-IDE resume work correctly. | | `blocker_log.md` | Logs CI/CD failures or missing user inputs. | | `pending_refactors.md` | Logs tech debt discovered outside the scope of a current task. | | `active_sessions/task_*.md` | The runtime memory for specific features/bugfixes. | +| `completed_sessions/` | Archived task session files after branch finish (optional). Created when the user confirms clearing the active task; session is moved here with a date suffix (e.g. `task_foo_YYYY-MM-DD.md`). | ## 2. The Engine (XML Skills) *Located in `.cursor/skills/`* @@ -22,8 +23,8 @@ This document lists every referenced path, its purpose, and how it fits into the | `code-review/SKILL.md` | Runs project-specific static analysis. | | `audit-compliance/SKILL.md` | IV&V agent that mathematically checks code determinism. | | `status-check/SKILL.md` | Reads `.agenticguild/` to diagnose blockers and rehydrate context. | -| `harvest-rules/SKILL.md` | Scans diffs to update architecture docs and `.cursorrules`. | -| `sync-docs/SKILL.md` | Keeps project docs in sync with branch changes (SPEC, SCHEMA_REFERENCE, DATA_FLOW_MAP, ADRs, etc.). | +| `harvest-rules/SKILL.md` | Proposes new rules from git diff, review_ledger, and active task session; writes approved rules to `.cursorrules` and SYSTEM_ARCHITECTURE. | +| `sync-docs/SKILL.md` | Keeps project docs in sync with branch diff and active task session (SPEC, SCHEMA_REFERENCE, DATA_FLOW_MAP, ADRs, .cursorrules, etc.); session is semantically analyzed and knowledge is placed by type. | | `pr-description/SKILL.md` | Outputs a Git-based PR description in a code block for the user to copy. | | `roadmap-manage/SKILL.md` | Add, prioritize, catalog items in the project roadmap. | | `roadmap-consult/SKILL.md` | Read-only view of roadmap: done, pending, priorities. | @@ -41,17 +42,20 @@ This document lists every referenced path, its purpose, and how it fits into the | `ADRs/` | Architectural Decision Records to bypass `SYSTEM_ARCHITECTURE.md`. | ## 4. Docs to Sync (sync-docs skill) -The `sync-docs` skill checks these docs against the branch diff and updates any that need changes. Only existing files are considered. +The `sync-docs` skill keeps docs in sync with both the branch diff and task memory. It checks these docs against the diff and, when an active task session exists, semantically analyzes the session and proposes updates by knowledge type (domain → SPEC, decisions → ADRs, data semantics → SCHEMA_REFERENCE enrichment, conventions/patterns → .cursorrules and SYSTEM_ARCHITECTURE). Only existing files are considered. | Doc | When to update | |-----|----------------| | `docs/core/SPEC.md` | Domain logic, entities, or requirements changed | -| `docs/core/SCHEMA_REFERENCE.md` | Schema or migrations changed (generated from raw schema) | +| `docs/core/SCHEMA_REFERENCE.md` | Schema or migrations changed (structure from raw schema; session can enrich with data semantics — why/when of tables and columns) | | `docs/core/DATA_FLOW_MAP.md` | Entity lifecycles or side-effects changed | | `docs/core/ADRs/` | New architectural decisions | | `docs/core/SYSTEM_ARCHITECTURE.md` | Stack, boundaries, or forbidden libs changed | +| `.cursorrules` | Conventions, patterns, or project rules changed (from diff or session) | **To add more docs:** Update this table in `docs/ai/EXPECTED_PROJECT_STRUCTURE.md`. Add the path and the condition that triggers an update. The sync-docs skill reads this list. +**Overlap with harvest-rules:** Both sync-docs and harvest-rules write to `.cursorrules` (and SYSTEM_ARCHITECTURE) by design: sync-docs adds session- and diff-derived conventions/patterns in one batch; harvest-rules proposes rule candidates from diff, review_ledger, and session for user approval, then writes approved ones. They are complementary. Harvest-rules already filters out candidates that duplicate rules already in `.cursorrules`; when both run in the same finish-branch flow, the user may reject harvest-rules candidates that repeat what sync-docs just added. + ## 5. Project-Specific Configuration ### 5.1 `.cursorrules` <project_config> diff --git a/skills/audit-compliance/SKILL.md b/skills/audit-compliance/SKILL.md index 634e9bd..efaf094 100644 --- a/skills/audit-compliance/SKILL.md +++ b/skills/audit-compliance/SKILL.md @@ -9,6 +9,10 @@ 2. When you see [PAUSE], you MUST completely stop generating text and wait for the user to reply. 3. Always end your response by summarizing our progress in a conversational manner and gently inviting the user to proceed. + + NEVER use any tool to execute `git commit`, `git push`, or `git merge`. These commands are STRICTLY FORBIDDEN. + When a commit is appropriate, output a suggested message as a plain-text code block only. The user runs all git commands themselves. + Act as a highly experienced, composed Principal Architect conducting an objective compliance review. Communicate your strict, unbiased findings in a professional, constructive, and conversational tone. When asking for input, be conversational instead of presenting rigid menus or dictating what the user should type. Hide the technical "phases and steps" of this workflow behind natural conversation. diff --git a/skills/explore-task/SKILL.md b/skills/explore-task/SKILL.md index 90e276a..3a866bb 100644 --- a/skills/explore-task/SKILL.md +++ b/skills/explore-task/SKILL.md @@ -36,7 +36,7 @@ First, check if `.agenticguild/current_state.md` points to an active session file. If it points to a session file: Verify the file actually exists. If it does, use the `view_file` tool to read it, summarize its current state, and ask what we need to figure out next. If it does not exist, treat this as a new session. - If this is a new session (no active task, or file is missing): Ask the user what they want to build or what problem they are trying to solve. Once they reply (in Step 1.2), you will derive `[name]` as a kebab-case slug, create `.agenticguild/active_sessions/task_[name].md`, and silently update `.agenticguild/current_state.md` to point to it. + If this is a new session (no active task, or file is missing): Ask the user what they want to build or what problem they are trying to solve. Once they reply (in Step 1.2), you will derive `[name]` as a kebab-case slug, create `.agenticguild/active_sessions/task_[name].md`, and silently update `.agenticguild/current_state.md` by setting `` to `task_[name].md` so the active task is unambiguous across IDEs. [PAUSE - AWAIT USER INPUT] @@ -44,7 +44,7 @@ Process the user's input. 1. Converse: Answer questions, propose architectural solutions, or ask clarifying questions to nail down edge cases. - 2. Update Memory: If this is the first exchange and `task_[name].md` hasn't been created, derive the name, create the file using the `write_to_file` tool, and update `.agenticguild/current_state.md`. You MUST use the `replace_file_content` tool to update the active memory file to reflect any new decisions, requirements, or constraints agreed upon in this exchange. + 2. Update Memory: If this is the first exchange and `task_[name].md` hasn't been created, derive the name, create the file using the `write_to_file` tool, and update `.agenticguild/current_state.md` by setting `` to `task_[name].md`. You MUST use the `replace_file_content` tool to update the active memory file to reflect any new decisions, requirements, or constraints agreed upon in this exchange. - If a major pivot occurs (e.g. "let's not use Redis"), move the old plan to `task_[name]_history.md` so the active file stays clean. 3. Domain Model (CbC): As domain entities and their data requirements become clear during the conversation, maintain a `## Domain Model` section in the memory file. For each entity introduced, document: - **Entity name** and its core responsibility diff --git a/skills/finish-branch/SKILL.md b/skills/finish-branch/SKILL.md index 04d3e9b..4f3c14a 100644 --- a/skills/finish-branch/SKILL.md +++ b/skills/finish-branch/SKILL.md @@ -71,7 +71,7 @@ Instruct the user to commit their code, push to the remote branch, and wait for CI feedback. - Update `.agenticguild/current_state.md` to indicate waiting status. + Update `.agenticguild/current_state.md` to indicate waiting status (e.g. in ``). Retain `` unchanged so status-check and resume still know which task is active. [PAUSE - AWAIT CI STATUS] @@ -103,7 +103,19 @@ Check if user-facing changes exist; if so, ensure `CHANGELOG.md` is updated. Use the `view_file` tool to read the active session file (if any) for ``. If this branch corresponds to a roadmap item, update `docs/ROADMAP.md`: move the item to Done, add today's date. If unclear, ask the user which roadmap item (if any) this branch completes. Then use the `view_file` tool to read and follow `.cursor/skills/pr-description/SKILL.md` until it yields. Remind the user to commit `docs/ROADMAP.md` if it was updated. - [PAUSE - BRANCH IS FINISHED] + [PAUSE - AWAIT CONFIRMATION] + + + + The branch is finished and task knowledge has been synced to the docs (sync-docs and harvest-rules). Conversationally tell the user that and ask: "Would you like me to clear the active task from memory? I'll set the active task to none and archive the session file to `.agenticguild/completed_sessions/` so it's no longer the current task — you can delete that folder or file later if you don't need the record. Reply yes to clear and archive, or no to leave it as-is for now." + + [PAUSE - AWAIT USER CONFIRMATION TO CLEAR TASK FROM MEMORY] + + + + Parse the user's reply. If they confirmed (e.g. "yes", "clear", "archive"): Read `.agenticguild/current_state.md` to get ``. If the pointer contains a session filename (e.g. `task_foo.md`): Create `.agenticguild/completed_sessions/` if it does not exist (e.g. run `mkdir -p .agenticguild/completed_sessions`). Move the session file from `.agenticguild/active_sessions/` to `.agenticguild/completed_sessions/` with a date suffix in the filename (e.g. `task_foo_YYYY-MM-DD.md`). Then update `.agenticguild/current_state.md`: set `` to `[NONE]` and `` to `[NONE]`, `[NONE]`, `[NONE]`. Confirm to the user that the task was cleared and the session file was archived. If the pointer was already [NONE] or the session file was missing, just update current_state to [NONE] and confirm. If they declined (e.g. "no", "keep"): Acknowledge; no changes. The session stays in active_sessions and the pointer unchanged; they can clear later via status-check or by running finish-branch again. + + [PAUSE - FINISH-BRANCH COMPLETE] diff --git a/skills/harvest-rules/SKILL.md b/skills/harvest-rules/SKILL.md index e5d766f..f7ebb98 100644 --- a/skills/harvest-rules/SKILL.md +++ b/skills/harvest-rules/SKILL.md @@ -30,19 +30,21 @@ - Check if `.agenticguild/review_ledger.md` exists. - If it exists, read its contents. Synthesize the recorded CI/Review diagnoses into actionable "Gotchas" or "Anti-Patterns" you should avoid in the future. - Combine these findings with your standard git diff analysis in the next step to propose a unified list of "New Rule Candidates". + Check if `.agenticguild/review_ledger.md` exists. If it exists, read its contents. Synthesize the recorded CI/Review diagnoses into actionable "Gotchas" or "Anti-Patterns" you should avoid in the future. + If an active task session exists: Use the `view_file` tool to read `.agenticguild/current_state.md` and parse ``. If it points to a session filename (e.g. `task_foo.md`) and that file exists at `.agenticguild/active_sessions/` + that filename, read the entire session file. Analyze it for rule-worthy content: conventions, patterns, anti-patterns, "we must/must not" decisions, naming or style choices. Treat these as additional candidates to merge with review_ledger and the diff in step 1.1. + Combine review_ledger findings (and any session-derived candidates) with your standard git diff analysis in the next step to propose a unified list of "New Rule Candidates". + [AUTO-TRANSITION TO 1.1] Read the `git diff` of the current branch against the default branch (e.g. `main`). Use the repository's default branch unless the project uses a different convention. Analyze the changes for new error handling, naming conventions, UI patterns, or data structures. + If you read a session file in step 1.0, include the session-derived rule candidates in your analysis. Merge with diff-based and review_ledger-based candidates into one unified list. Scan the `docs/` directory and `.cursorrules` to determine where these new patterns should be codified. - Before outputting candidates: Verify proposed rules do not contradict or duplicate rules already in `docs/core/SYSTEM_ARCHITECTURE.md` or `.cursorrules`. Filter out any that do. + Before outputting candidates: Verify proposed rules do not contradict or duplicate rules already in `docs/core/SYSTEM_ARCHITECTURE.md` or `.cursorrules`. Filter out any that do. If run after sync-docs in the same workflow (e.g. finish-branch), skip candidates that are semantically equivalent to rules likely just added to `.cursorrules` by sync-docs to avoid near-duplicates. If the changes imply future work (e.g. a new pattern that will need follow-up features), consider suggesting adding a roadmap item to `docs/ROADMAP.md` via the roadmap-manage skill. - Output a list of "New Rule Candidates" formatted as: `[Target File] -> [Proposed Rule Addition]`. + Output a list of "New Rule Candidates" formatted as: `[Target File] -> [Proposed Rule Addition]`. Optionally note which candidates came from diff, review_ledger, or session when it helps the user. [PAUSE - WRITE LOCK ACTIVE. AWAIT USER APPROVAL OF CANDIDATES] diff --git a/skills/pr-description/SKILL.md b/skills/pr-description/SKILL.md index e69e5bb..7549787 100644 --- a/skills/pr-description/SKILL.md +++ b/skills/pr-description/SKILL.md @@ -22,6 +22,9 @@ + NEVER use any tool to execute `git commit`, `git push`, or `git merge`. These commands are STRICTLY FORBIDDEN. + When a commit is appropriate, output a suggested message as a plain-text code block only. The user runs all git commands themselves. + 1. Do NOT use markdown link syntax for any file references in the PR description. IDEs convert local paths into broken `cci:7://file:///` hyperlinks that are useless when pasted into GitHub. 2. For files that exist in the repo: use plain backtick code formatting only — e.g. `docs/core/SYSTEM_ARCHITECTURE.md`. 3. For deleted or renamed files: use backtick formatting only — never link syntax. diff --git a/skills/process-feedback/SKILL.md b/skills/process-feedback/SKILL.md index 5b06cf3..c08efd2 100644 --- a/skills/process-feedback/SKILL.md +++ b/skills/process-feedback/SKILL.md @@ -10,6 +10,10 @@ 2. The ONLY time you pause for permission is if the fix requires a massive, multi-file architectural refactor. 3. You must maintain the illusion of a 'subroutine'. Once finished, you MUST seamlessly resume whatever skill or task was active before you were triggered. + + NEVER use any tool to execute `git commit`, `git push`, or `git merge`. These commands are STRICTLY FORBIDDEN. + When a commit is appropriate, output a suggested message as a plain-text code block only. The user runs all git commands themselves. + @@ -20,6 +24,7 @@ If multiple fixes affect the same file, consolidate them into a single file editing tool call if possible, or sequence them carefully. Immediately use file editing tools to deploy all the fixes to the codebase. + [AUTO-TRANSITION TO 1.2] @@ -29,6 +34,7 @@ - **Diagnosis/Why it failed:** [The root cause] - **Fix:** [What was changed] + [AUTO-TRANSITION TO 1.3] @@ -36,6 +42,7 @@ Immediately append: "Resuming previous task..." Perform a context-lookback to identify what phase/step of what skill was running before this feedback was pasted, and seamlessly continue executing that step. Do NOT wait for user input unless the previous task was also waiting for user input. + [AUTO-TRANSITION TO PREVIOUS TASK] diff --git a/skills/roadmap-consult/SKILL.md b/skills/roadmap-consult/SKILL.md index 5b6fc31..c76c8d1 100644 --- a/skills/roadmap-consult/SKILL.md +++ b/skills/roadmap-consult/SKILL.md @@ -8,6 +8,10 @@ 1. NEVER modify the roadmap during this skill. 2. Your ONLY job is to read (using the `view_file` tool) and report. + + NEVER use any tool to execute `git commit`, `git push`, or `git merge`. These commands are STRICTLY FORBIDDEN. + When a commit is appropriate, output a suggested message as a plain-text code block only. The user runs all git commands themselves. + Act as a highly experienced, composed, and helpfully collaborative pair programmer, and an approachable, reliable teammate. Communicate in a conversational, professional, and pleasant tone. Present the roadmap information in an easy-to-read, natural way rather than a rigid report. Hide the technical "phases and steps" behind natural conversation. diff --git a/skills/roadmap-manage/SKILL.md b/skills/roadmap-manage/SKILL.md index dd17e0f..f2097dd 100644 --- a/skills/roadmap-manage/SKILL.md +++ b/skills/roadmap-manage/SKILL.md @@ -9,6 +9,10 @@ 2. When you see [PAUSE], you MUST completely stop generating text and wait for the user to reply. 3. Always end your response by summarizing our progress in a conversational manner and gently inviting the user to proceed. + + NEVER use any tool to execute `git commit`, `git push`, or `git merge`. These commands are STRICTLY FORBIDDEN. + When a commit is appropriate, output a suggested message as a plain-text code block only. The user runs all git commands themselves. + Act as a highly experienced, composed, and helpfully collaborative pair programmer, and an approachable, reliable teammate. Communicate in a conversational, professional, and pleasant tone. When asking for input or reporting changes, be conversational and supportive. Hide the technical "phases and steps" behind natural conversation. diff --git a/skills/start-task/SKILL.md b/skills/start-task/SKILL.md index 750a39d..4aabded 100644 --- a/skills/start-task/SKILL.md +++ b/skills/start-task/SKILL.md @@ -62,7 +62,7 @@ First, check if `.agenticguild/current_state.md` points to an active session file (e.g., passed over from `explore-task`). - If it points to an active session file: Verify the file actually exists before reading it using the `view_file` tool. If the file exists and already contains a populated `` block, acknowledge the spec is locked and [AUTO-TRANSITION TO 3.0]. If it exists but the plan is empty/missing, proceed with the drafting steps below. - - If no active session is pointed to, or the file is missing: Derive `[name]` as a short, kebab-case slug from the task description and silently create a new session file in `.agenticguild/active_sessions/` named `task_[name].md` using the `write_to_file` tool. If the task came from the roadmap, include `` in the session metadata. Silently update `.agenticguild/current_state.md` to point to this new file. Write the task classification and description into the session file. + - If no active session is pointed to, or the file is missing: Derive `[name]` as a short, kebab-case slug from the task description and silently create a new session file in `.agenticguild/active_sessions/` named `task_[name].md` using the `write_to_file` tool. If the task came from the roadmap, include `` in the session metadata. Silently update `.agenticguild/current_state.md`: set `` to the session filename (e.g. `task_[name].md`) so the active task is unambiguous across IDEs. Write the task classification and description into the session file. Drafting the plan (only if no plan exists yet): You MUST use the `replace_file_content` tool to draft the step-by-step implementation plan directly inside the `` block of the `task_[name].md` file ON DISK. Use `[Description]` format. VERIFICATION LOCK: Before asking for user approval, you MUST verify the file `task_[name].md` was successfully updated on the filesystem. Before responding to the user, you MUST explicitly state in your response that the file was successfully updated on disk. Do not present the plan if the file does not exist. - If Bugfix: Step 1 MUST be "Write a failing test that reproduces the bug." diff --git a/skills/status-check/SKILL.md b/skills/status-check/SKILL.md index 79f4588..6613b20 100644 --- a/skills/status-check/SKILL.md +++ b/skills/status-check/SKILL.md @@ -8,6 +8,10 @@ 1. NEVER generate or modify application code during this skill. 2. Your ONLY job is diagnosis and context rehydration. + + NEVER use any tool to execute `git commit`, `git push`, or `git merge`. These commands are STRICTLY FORBIDDEN. + When a commit is appropriate, output a suggested message as a plain-text code block only. The user runs all git commands themselves. + Act as a highly experienced, composed, and helpfully collaborative pair programmer, and an approachable, reliable teammate. Communicate in a conversational, professional, and pleasant tone. When providing status, avoid presenting rigid robotic reports or dictating what the user should type. Make the status easy to digest and naturally guide the user on what to tackle next. @@ -22,20 +26,21 @@ - Expected format: `` = session filename (e.g. `task_foo.md`) or `[NONE]`; `` contains ``, ``, ``. + Expected format: `` = session filename (e.g. `task_foo.md`) or `[NONE]`; `` contains ``, ``, ``. When multiple session files exist in `.agenticguild/active_sessions/`, the active task pointer MUST be set to the session filename so the active task is unambiguous across IDEs and branches; otherwise status-check cannot assume a single task. - Use the `view_file` tool to read `.agenticguild/current_state.md`, the active session file in `.agenticguild/active_sessions/` (indicated by current state), the `` block inside that session file, `git status`, and `git diff` against the default branch (e.g. `main`). - If `docs/ROADMAP.md` exists: Count Done, In Progress, Pending, Backlog to get a sense of overall progress. - Give the user a clear, helpful snapshot of where we currently are: - 1. Overall Progress: A pleasant, helpful summary of the active skill, phase, and roadmap progress. - 2. Current Step: What we are actively working on right now. - 3. Blockers: Note any blockers (use the `view_file` tool to read from `.agenticguild/blocker_log.md`) or failing tests we need to tackle. - 4. Next Steps: Instead of a strict command, finish by asking them conversationally if they are ready to jump back into the current step and proceed. + 1. Discover sessions: List `.agenticguild/active_sessions/*.md` (e.g. via list_dir or glob), excluding `task_template.md`, to get all session files. + 2. Read state: Use the `view_file` tool to read `.agenticguild/current_state.md`. Parse `` — it should contain a session filename (e.g. `task_foo.md`) or `[NONE]`. + 3. Resolve active task: + - If `` contains a session filename (e.g. `task_foo.md`) and that file exists in `active_sessions/`: Treat that as the active task. Use the `view_file` tool to read that session file, its `` block, `git status`, and `git diff` against the default branch (e.g. `main`). If `docs/ROADMAP.md` exists, count Done, In Progress, Pending, Backlog. Give the user a clear, helpful snapshot: (1) Overall Progress: summary of active skill, phase, roadmap progress; (2) Current Step: what we are actively working on; (3) Blockers: from `.agenticguild/blocker_log.md` or failing tests; (4) Next Steps: ask conversationally if they are ready to jump back into the current step. Then [PAUSE]. + - If `` contains a session filename but that file does NOT exist in `active_sessions/`: Treat as stale pointer (e.g. file deleted, renamed, or typo). List the session files you found (and optionally any "In Progress" items from `docs/ROADMAP.md` if it exists). Tell the user the pointer references a missing file and ask them to confirm which task is active or to set `` in `.agenticguild/current_state.md` to a valid session filename. Then [PAUSE]. Do not report any one task as current until they fix the pointer or confirm. + - If `` is missing, empty, or `[NONE]` and there are two or more session files: Do NOT assume a single task. List the session filenames you found (and optionally any "In Progress" items from `docs/ROADMAP.md` if it exists). Tell the user the active task could not be determined and ask them to confirm which task is active, or to set `` in `.agenticguild/current_state.md` to the correct session filename (e.g. `task_i18n-support.md`). Then [PAUSE]. Do not report any one task as current until the user confirms or sets the pointer. + - If there is only one session file (or none): If pointer is set and file exists, proceed as in the first bullet. If pointer is missing or `[NONE]` and there is exactly one session file, you may treat it as the active task and report status, but still suggest setting `` for cross-IDE consistency. If there are zero session files and the pointer is missing or `[NONE]`: Report that no active tasks were found; suggest starting a new task (start-task or explore-task) or checking the roadmap. Then [PAUSE]. + 4. Blockers: When reporting status, note any blockers (read `.agenticguild/blocker_log.md`) or failing tests. [PAUSE - AWAIT CONFIRMATION TO RESUME OR TACTICAL COMMAND] diff --git a/skills/sync-docs/SKILL.md b/skills/sync-docs/SKILL.md index a6c8a76..3388d58 100644 --- a/skills/sync-docs/SKILL.md +++ b/skills/sync-docs/SKILL.md @@ -1,7 +1,7 @@ sync-docs - Keeps project docs in sync with branch changes. Analyzes the diff against the docs-to-sync list, then applies all necessary updates in one batch. + Keeps project docs in sync with branch changes and with task memory. Uses two inputs: (1) the branch diff — to infer code/schema-driven doc updates; (2) the active task session file when present — semantically analyzed so domain, decisions, data semantics, and rule-worthy content are pushed to the right docs. Does not dump raw session content; synthesizes and places knowledge by type. @@ -26,14 +26,30 @@ If they are missing, pause our work and gently let the user know we need these files to start. Offer to gracefully initialize the project templates for them. If the user says yes, run sync.sh (or equivalent) if available; otherwise create minimal placeholders from EXPECTED_PROJECT_STRUCTURE. Do NOT hallucinate contents without user confirmation. + + When an active session file exists, semantically analyze its full content (any structure). Classify fragments by knowledge type and map to the doc(s) below. Do not dump raw session text; synthesize and place. Session structure is free-form; analysis is semantic. + + Domain, entities, invariants, value objects, glossary → SPEC.md; optionally DATA_FLOW_MAP.md (lifecycles). + Architectural decisions, path not taken, rejections and rationale → ADRs/. + Stack, boundaries, "must not use X", constraints → SYSTEM_ARCHITECTURE.md, .cursorrules. + Conventions, patterns, anti-patterns (harvest-worthy rules) → .cursorrules, docs/core/SYSTEM_ARCHITECTURE.md. + Data semantics: why and when of data (tables, columns, entities) → SCHEMA_REFERENCE.md (enrichment; structure still from schema file). + Testing approach, mocking strategy → TESTING_STRATEGY_MATRIX.md or project testing doc if present. + Risks, assumptions, trade-offs → SPEC or ADRs. Open questions, future work → ROADMAP, SPEC, or ADRs. + + + - Read the git diff of the current branch against the default branch (e.g. `main`). - Use the `view_file` tool to read the "Docs to Sync" table in `docs/ai/EXPECTED_PROJECT_STRUCTURE.md` to get the list of docs and their update conditions. - For each doc in the list that exists in the project: determine whether the branch changes require updates based on the condition. - Output a neat, conversational report: [Doc] → [Needs update: Yes/No] + brief reason. Ask the user if they'd like you to proceed with these updates. + 1. Read the git diff of the current branch against the default branch (e.g. `main`). + 2. Use the `view_file` tool to read the "Docs to Sync" table in `docs/ai/EXPECTED_PROJECT_STRUCTURE.md` (or `playbooks/EXPECTED_PROJECT_STRUCTURE.md` if the former is missing) to get the list of docs and their update conditions. + 3. Resolve and read session: Use the `view_file` tool to read `.agenticguild/current_state.md` and parse ``. If the pointer contains a session filename (e.g. `task_foo.md`) and the file exists at `.agenticguild/active_sessions/` + that filename, read the entire session file. If no pointer or file is missing, continue with diff-only. + 4. Diff-based analysis: For each doc in the table that exists in the project, determine whether the branch diff requires updates based on the condition. Build a diff-derived list: [Doc] → needs update (Yes/No) + reason. + 5. Session-based analysis: If a session file was read, semantically analyze the whole session (all sections, any structure). Classify meaningful fragments using the <knowledge_type_map> (domain, decisions, data semantics, conventions/patterns, testing, risks, etc.). For each classified fragment, determine which doc(s) should receive content. Build a session-derived list: [Doc] ← [knowledge type]: brief description of what to add (do not dump raw session text). Include SCHEMA_REFERENCE when the session discusses data (why/when of tables/columns). Include .cursorrules and SYSTEM_ARCHITECTURE for conventions, patterns, anti-patterns. + 6. Merge: Combine the two lists. If a doc is touched by both diff and session, mark source "both" and merge reasons. Result: one list per doc with source (diff | session | both) and reason. + 7. Report: Output a neat, conversational report: [Doc] → [Needs update: Yes/No] [Source: diff | session | both] + brief reason. Ask the user if they'd like you to proceed with these updates. [PAUSE - AWAIT USER CONFIRMATION TO PROCEED OR SKIP] @@ -62,14 +78,15 @@ - For each doc that needs updates, apply the changes in a single batch using the `replace_file_content` or `write_to_file` tools: - - **SCHEMA_REFERENCE.md**: Use the schema path resolved in Phase 2 (or skip if user refused). Use the `view_file` tool to read the raw schema file, map to SPEC.md, generate/overwrite. - - **SPEC.md**: Update domain logic, entities, glossary, or REQ-IDs as implied by the diff. - - **DATA_FLOW_MAP.md**: Update entity lifecycles or side-effects. - - **ADRs/**: Add or update ADRs for new architectural decisions. - - **SYSTEM_ARCHITECTURE.md**: Update stack, boundaries, or forbidden libs. - Output a helpful summary of what was updated. - Remind the user conversationally: "Just a heads up, to have more docs updated automatically, you can add them to the 'Docs to Sync' table in `docs/ai/EXPECTED_PROJECT_STRUCTURE.md`." + For each doc that needs updates, apply the changes in a single batch using the `replace_file_content` or `write_to_file` tools. Use the merged list from Step 1.1 (source: diff, session, or both). + - **SCHEMA_REFERENCE.md**: Use the schema path resolved in Phase 2 (or skip if user refused). Read the raw schema file and generate the structure (tables, columns, mapping to SPEC). If the session was read and contains data semantics (why and when of data, tables, columns), add those as short semantic notes in the appropriate places (e.g. per table or section). Do not replace structure with session content; enrich the generated doc with session-derived "why/when" where relevant. + - **SPEC.md**: Update domain logic, entities, glossary, or REQ-IDs from the diff and/or session. When source is "both", merge into one coherent update (session gives domain/entities/glossary; diff may add code-implied details). Use session metadata (req_id, roadmap_item) when present. Synthesize; do not paste raw session text. + - **DATA_FLOW_MAP.md**: Update entity lifecycles or side-effects from diff and/or session. + - **ADRs/**: Add or update ADRs from diff and/or session (decisions, path not taken, rationale). Synthesize into concise ADR prose; do not dump raw session. + - **SYSTEM_ARCHITECTURE.md**: Update stack, boundaries, forbidden libs, and conventions/patterns from diff and/or session. Session-derived rules (conventions, anti-patterns) go here. + - **.cursorrules**: When session (or diff) yields conventions, patterns, or anti-patterns, add them in the appropriate project rules section. Align with harvest-rules targets. + Output a helpful summary of what was updated and whether each came from diff, session, or both. + Remind the user conversationally: "Just a heads up, to have more docs updated automatically, you can add them to the 'Docs to Sync' table in EXPECTED_PROJECT_STRUCTURE." [PAUSE - DOCS SYNCED. SKILL COMPLETE] diff --git a/skills/update-agentic-guild/SKILL.md b/skills/update-agentic-guild/SKILL.md index d53b69b..512ed22 100644 --- a/skills/update-agentic-guild/SKILL.md +++ b/skills/update-agentic-guild/SKILL.md @@ -45,8 +45,9 @@ Ensure required directories exist, creating them if absent: - - `.cursor/skills/{start-task,finish-branch,harvest-rules,status-check,code-review,audit-compliance,sync-docs,pr-description,roadmap-manage,roadmap-consult,update-agentic-guild,explore-task}` + - `.cursor/skills/{start-task,finish-branch,harvest-rules,status-check,code-review,audit-compliance,sync-docs,pr-description,roadmap-manage,roadmap-consult,update-agentic-guild,explore-task,process-feedback}` - `.agenticguild/active_sessions` + - `.agenticguild/completed_sessions` - `docs/{ai,core,features,audit,guides}` and `docs/core/ADRs` - `.github` @@ -61,7 +62,7 @@ .agenticguild/* !.agenticguild/.gitkeep ``` - Ensure `.agenticguild/.gitkeep` and `.agenticguild/active_sessions/.gitkeep` exist as empty files (create if missing). + Ensure `.agenticguild/.gitkeep`, `.agenticguild/active_sessions/.gitkeep`, and `.agenticguild/completed_sessions/.gitkeep` exist as empty files (create directories and files if missing). [AUTO-TRANSITION TO 1.3] diff --git a/sync.sh b/sync.sh index 0d7976e..c39d3b5 100755 --- a/sync.sh +++ b/sync.sh @@ -21,7 +21,7 @@ fi # 2. Create necessary directories echo "📁 Building directory structure..." mkdir -p .cursor/skills -mkdir -p .agenticguild/active_sessions +mkdir -p .agenticguild/active_sessions .agenticguild/completed_sessions mkdir -p docs/{ai,core,features,audit,guides} mkdir -p docs/core/ADRs mkdir -p .github @@ -50,6 +50,7 @@ fi # Ensure .gitkeep exists so the folder structure survives git touch .agenticguild/.gitkeep touch .agenticguild/active_sessions/.gitkeep +touch .agenticguild/completed_sessions/.gitkeep # 4. Download files according to the Sync Registry echo "📥 Syncing files from registry..." diff --git a/templates/core/AGENTIC_GUILD_RULES.md b/templates/core/AGENTIC_GUILD_RULES.md index da643f6..e2f0b8d 100644 --- a/templates/core/AGENTIC_GUILD_RULES.md +++ b/templates/core/AGENTIC_GUILD_RULES.md @@ -6,7 +6,7 @@ You possess persistent memory. You must use the `.agenticguild/` directory to survive context window limits and conversational tangents. - 1. State Tracking: When executing any skill, you MUST write your current `` and `` to `.agenticguild/current_state.md`. + 1. State Tracking: When executing any skill, you MUST write your current `` and `` to `.agenticguild/current_state.md`. When a task is active, you MUST also write the active session filename to `` (e.g. `task_foo.md`) so the active task is unambiguous across IDEs and chats. 2. Resuming: If the user says "Resume Task", "Status Check", or "Where were we?", you MUST read `.agenticguild/current_state.md` to rehydrate your context before answering. 3. Artifact Generation: Log any identified tech-debt, blocked tasks, or test-coverage gaps into the appropriate artifact files within `.agenticguild/` rather than keeping them in temporary chat context. @@ -52,6 +52,7 @@ Read `.cursor/skills/pr-description/SKILL.md` Read `.cursor/skills/roadmap-manage/SKILL.md` Read `.cursor/skills/roadmap-consult/SKILL.md` + Read `.cursor/skills/update-agentic-guild/SKILL.md` diff --git a/templates/core/memory_scaffold/current_state.md b/templates/core/memory_scaffold/current_state.md index dc10fec..19c92fd 100644 --- a/templates/core/memory_scaffold/current_state.md +++ b/templates/core/memory_scaffold/current_state.md @@ -1,4 +1,5 @@ + [NONE]