diff --git a/.github/agents/Management.agent.md b/.github/agents/Management.agent.md index d01d687d..fc38d8ad 100644 --- a/.github/agents/Management.agent.md +++ b/.github/agents/Management.agent.md @@ -43,7 +43,7 @@ You are "lazy" in the smartest way possible. You never do what a subordinate can - **Identify Goal**: Understand the user's request. - **STOP**: Do not look at the code. Do not run `list_dir`. No code is to be changed or implemented until there is a fundamentally sound plan of action that has been approved by the user. - **Action**: Immediately call `Planning` subagent. - - *Prompt*: "Research the necessary files for '{user_request}' and write a comprehensive plan detailing as many specifics as possible to `docs/plans/current_spec.md`. Be an artist with directions and discriptions. Include file names, function names, and component names wherever possible. Break the plan into phases based on the least amount of requests. Include a Commit Slicing Strategy section that decides whether to split work into multiple PRs and, when split, defines PR-1/PR-2/PR-3 scope, dependencies, and acceptance criteria. Review and suggest updaetes to `.gitignore`, `codecov.yml`, `.dockerignore`, and `Dockerfile` if necessary. Return only when the plan is complete." + - *Prompt*: "Research the necessary files for '{user_request}' and write a comprehensive plan detailing as many specifics as possible to `docs/plans/current_spec.md`. Be an artist with directions and discriptions. Include file names, function names, and component names wherever possible. Break the plan into phases based on the least amount of requests. Include a Commit Slicing Strategy section that organizes work into logical commits within a single PR — one feature = one PR, with ordered commits (Commit 1, Commit 2, …) each defining scope, files, dependencies, and validation gates. Review and suggest updaetes to `.gitignore`, `codecov.yml`, `.dockerignore`, and `Dockerfile` if necessary. Return only when the plan is complete." - **Task Specifics**: - If the task is to just run tests or audits, there is no need for a plan. Directly call `QA_Security` to perform the tests and write the report. If issues are found, return to `Planning` for a remediation plan and delegate the fixes to the corresponding subagents. @@ -59,15 +59,13 @@ You are "lazy" in the smartest way possible. You never do what a subordinate can - **Ask**: "Plan created. Shall I authorize the construction?" 4. **Phase 4: Execution (Waterfall)**: - - **Single-PR or Multi-PR Decision**: Read the Commit Slicing Strategy in `docs/plans/current_spec.md`. - - **If single PR**: + - **Read Commit Slicing Strategy**: Read the Commit Slicing Strategy in `docs/plans/current_spec.md` to understand the ordered commits. + - **Single PR, Multiple Commits**: All work ships as one PR. Each commit maps to a phase in the plan. - **Backend**: Call `Backend_Dev` with the plan file. - **Frontend**: Call `Frontend_Dev` with the plan file. - - **If multi-PR**: - - Execute in PR slices, one slice at a time, in dependency order. - - Require each slice to pass review + QA gates before starting the next slice. - - Keep every slice deployable and independently testable. - - **MANDATORY**: Implementation agents must perform linting and type checks locally before declaring their slice "DONE". This is a critical step that must not be skipped to avoid broken commits and security issues. + - Execute commits in dependency order. Each commit must pass its validation gates before the next commit begins. + - The PR is merged only when all commits are complete and all DoD gates pass. + - **MANDATORY**: Implementation agents must perform linting and type checks locally before declaring their commit "DONE". This is a critical step that must not be skipped to avoid broken commits and security issues. 5. **Phase 5: Review**: - **Supervisor**: Call `Supervisor` to review the implementation against the plan. Provide feedback and ensure alignment with best practices. @@ -80,7 +78,7 @@ You are "lazy" in the smartest way possible. You never do what a subordinate can - **Docs**: Call `Docs_Writer`. - **Manual Testing**: create a new test plan in `docs/issues/*.md` for tracking manual testing focused on finding potential bugs of the implemented features. - **Final Report**: Summarize the successful subagent runs. - - **PR Roadmap**: If split mode was used, include a concise roadmap of completed and remaining PR slices. + - **Commit Roadmap**: Include a concise summary of completed and remaining commits within the PR. **Mandatory Commit Message**: When you reach a stopping point, provide a copy and paste code block commit message at the END of the response on format laid out in `.github/instructions/commit-message.instructions.md` - **STRICT RULES**: diff --git a/.github/agents/Planning.agent.md b/.github/agents/Planning.agent.md index 561e9fdf..5e7d8ae9 100644 --- a/.github/agents/Planning.agent.md +++ b/.github/agents/Planning.agent.md @@ -38,7 +38,7 @@ You are a PRINCIPAL ARCHITECT responsible for technical planning and system desi - Specify database schema changes - Document component interactions and data flow - Identify potential risks and mitigation strategies - - Determine PR sizing and whether to split the work into multiple PRs for safer and faster review + - Determine commit sizing and how to organize work into logical commits within a single PR for safer and faster review 3. **Documentation**: - Write plan to `docs/plans/current_spec.md` @@ -46,10 +46,10 @@ You are a PRINCIPAL ARCHITECT responsible for technical planning and system desi - Break down into implementable tasks using examples, diagrams, and tables - Estimate complexity for each component - Add a **Commit Slicing Strategy** section with: - - Decision: single PR or multiple PRs + - Decision: single PR with ordered logical commits (one feature = one PR) - Trigger reasons (scope, risk, cross-domain changes, review size) - - Ordered PR slices (`PR-1`, `PR-2`, ...), each with scope, files, dependencies, and validation gates - - Rollback and contingency notes per slice + - Ordered commits (`Commit 1`, `Commit 2`, ...), each with scope, files, dependencies, and validation gates + - Rollback and contingency notes for the PR as a whole 4. **Handoff**: - Once plan is approved, delegate to `Supervisor` agent for review. diff --git a/.github/instructions/subagent.instructions.md b/.github/instructions/subagent.instructions.md index b2c0f237..ef0af637 100644 --- a/.github/instructions/subagent.instructions.md +++ b/.github/instructions/subagent.instructions.md @@ -23,21 +23,21 @@ runSubagent({ - Validate: `plan_file` exists and contains a `Handoff Contract` JSON. - Kickoff: call `Planning` to create the plan if not present. -- Decide: check if work should be split into multiple PRs (size, risk, cross-domain impact). +- Decide: check how to organize work into logical commits within a single PR (size, risk, cross-domain impact). - Run: execute `Backend Dev` then `Frontend Dev` sequentially. - Parallel: run `QA and Security`, `DevOps` and `Doc Writer` in parallel for CI / QA checks and documentation. - Return: a JSON summary with `subagent_results`, `overall_status`, and aggregated artifacts. 2.1) Multi-Commit Slicing Protocol -- If a task is large or high-risk, split into PR slices and execute in order. -- Each slice must have: +- All work for a single feature ships as one PR with ordered logical commits. +- Each commit must have: - Scope boundary (what is included/excluded) - - Dependency on previous slices - - Validation gates (tests/scans required for that slice) - - Explicit rollback notes -- Do not start the next slice until the current slice is complete and verified. -- Keep each slice independently reviewable and deployable. + - Dependency on previous commits + - Validation gates (tests/scans required for that commit) + - Explicit rollback notes for the PR as a whole +- Do not start the next commit until the current commit is complete and verified. +- Keep each commit independently reviewable within the PR. 3) Return Contract that all subagents must return @@ -55,7 +55,7 @@ runSubagent({ - On a subagent failure, the Management agent must capture `tests.output` and decide to retry (1 retry maximum), or request a revert/rollback. - Clearly mark the `status` as `failed`, and include `errors` and `failing_tests` in the `summary`. -- For multi-PR execution, mark failed slice as blocked and stop downstream slices until resolved. +- For multi-commit execution, mark failed commit as blocked and stop downstream commits until resolved. 5) Example: Run a full Feature Implementation