ideal-agentic-workflow 1.0.0

package/skills/s10-git-commit/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: "S10 Git Commit"
+description: "Executes the final staging and commit phase, strictly enforcing conventional commit formatting, atomic sizing, and workflow completion gates."
+---
+
+# S10 Git Commit
+
+## 1. Introduction and Purpose
+This document defines the strict execution protocol for the S10 Git Commit phase within the `ideal-agentic-workflow` plugin. 
+The S10 phase is the critical finalization step where peer-reviewed, tested code is permanently recorded into the project's version control history.
+The orchestrating agent MUST execute the protocols defined below to guarantee that the repository history remains pristine, traceable, and automation-friendly.
+Generating chaotic, massive, or poorly formatted commits completely undermines the discipline enforced during the previous nine phases of the workflow.
+This rigorous approach ensures that every change is easily auditable and properly scoped into logical, atomic units.
+The orchestrating agent MUST strictly manage the commit sizing, enforce exact formatting rules, and verify task completion before staging.
+Failure to properly execute this phase will break semantic versioning tools and severely degrade the maintainability of the project.
+The S10 phase explicitly transitions the workflow from active development into documentation synchronization.
+
+## 2. Hard Gating and Modal Sizing Rules
+The integrity of the commit history relies entirely on the agent verifying that all assigned work is actually finished before modifying the git tree. 
+The agent MUST explicitly verify the following absolute gating rule before running any `git commit` commands.
+The agent MUST acknowledge the absolute prohibition: "No commit before all tasks [x] in task.md."
+If any task in the `.agents/session-[SHA]/task.md` file remains incomplete or marked as in-progress (`[/]`), the agent MUST immediately loop back to S6 Coding.
+Once the progression gate is cleared, the agent MUST apply the correct commit sizing constraints based on the active session mode.
+For Standard and Duolithic Modes, the agent MUST adhere to the sizing rule: "~50-150 insertions per commit (guideline)."
+The agent MUST "never split atomic units", and if a commit exceeds 150 insertions, the body MUST contain "one sentence explaining why this is one atomic unit".
+For Fast Mode, the agent MUST apply the override: "No size target — commit what the fix requires."
+For the Trivial Protocol, the agent MUST apply the override: "Single commit with type `docs` or `chore`."
+
+### 2.1 Commit Formatting Protocol
+Before finalizing the git commit message, the agent MUST explicitly instruct itself to read `resources/commit-examples.md` and `resources/breaking-change-guide.md`. 
+The agent MUST study these resources to ensure its drafted message exactly matches the project's rigid stylistic requirements.
+The agent MUST enforce the core formatting rules: the subject line MUST be a maximum of 72 characters, imperative mood, and follow the Conventional Commits format.
+The agent MUST include a mandatory blank line between the subject and the body.
+The agent MUST ensure the body is always present, entirely lowercase, and restricted to a maximum of 150 characters (excluding breaking change footers).
+The agent MUST apply the `BREAKING CHANGE:` footer precisely as defined in the guide if the commit introduces incompatible API modifications.
+The agent MUST NOT generate commits that violate these structural boundaries under any circumstances.
+The agent MUST meticulously review its drafted commit message against these constraints before execution.

package/skills/s10-git-commit/resources/breaking-change-guide.md

@@ -0,0 +1,33 @@
+# Breaking Change Guide
+
+## 1. Introduction and Purpose
+This document provides the mandatory instructions for documenting breaking changes during the S10 Git Commit phase. 
+In complex software architectures, modifying public APIs, altering database schemas, or changing established configuration formats often breaks downstream dependents.
+Without a standardized method for signaling these disruptions, consumers of the codebase will experience unexpected failures during deployments.
+By enforcing the Conventional Commits breaking change footer, the workflow ensures that automated semantic versioning tools correctly bump major version numbers.
+The agent MUST utilize this specific footer format whenever a commit introduces an incompatible API change.
+The agent MUST NOT attempt to hide or obscure breaking changes within standard feature or fix commits.
+Failure to properly tag a breaking change is considered a critical architectural violation.
+The agent MUST follow the formatting rules defined below exactly.
+
+## 2. Formatting the Breaking Change Footer
+The breaking change footer is a specific string appended to the very bottom of the commit message body. 
+It explicitly flags the commit to release automation tools, ensuring that major version bumps are triggered automatically.
+The agent MUST add exactly one blank line after the mandatory lowercase commit body, followed immediately by the footer text.
+The footer MUST begin exactly with the string `BREAKING CHANGE: ` (including the space after the colon).
+Following the colon, the agent MUST provide a clear, concise description of what broke and how consumers must migrate their implementations.
+The agent MUST NOT use alternative phrasing like "Breaking:" or "Warning: breaking change".
+The agent MUST strictly adhere to the following structure for any incompatible change.
+The agent MUST NOT omit the migration instructions.
+
+### 2.1 Example Format
+The following example demonstrates the correct usage of the breaking change footer. 
+The agent MUST study this example to understand the spatial relationship between the body text and the footer itself.
+The agent MUST replicate this exact spacing and capitalization pattern.
+The agent MUST clearly describe the mitigation path for users affected by the breaking change.
+The agent MUST NOT use generic filler text for the migration instructions.
+- `feat: replace legacy authentication provider`
+  
+  `migrated all authentication endpoints from the legacy jwt service to the new oauth2 provider. this atomic unit replaces the core security module.`
+  
+  `BREAKING CHANGE: the /api/v1/login endpoint no longer accepts basic auth. consumers must now use the /api/v2/oauth/authorize flow.`

package/skills/s10-git-commit/resources/commit-examples.md

@@ -0,0 +1,76 @@
+# Commit Examples Reference
+
+## 1. Introduction and Purpose
+This document provides the definitive repository of correctly formatted Git commit messages for the S10 Git Commit phase. 
+Because autonomous agents frequently struggle with maintaining discipline in version control histories, these examples serve as mandatory structural templates.
+Without this rigid reference, agents often generate monolithic commits with missing context, violating the project's formatting constraints.
+By mimicking the successful patterns demonstrated below, the workflow guarantees that the commit history remains highly readable, easily searchable, and automation-friendly.
+The agent MUST consult these examples before formatting any commit message during the execution of S10.
+The agent MUST explicitly format its own commit messages to mirror the structure, tone, and character limits shown in the "Good Examples" section.
+The agent MUST NOT replicate any of the flawed structures demonstrated in the "Bad Examples" section under any circumstances.
+Failure to adhere to these formats will break release automation scripts and severely degrade the repository's auditability.
+
+## 2. Good Examples (Allowed)
+The following examples demonstrate perfectly formatted commit messages that adhere to all `ideal-agentic-workflow` constraints. 
+Each example strictly follows the Conventional Commits specification, utilizing an imperative subject line limited to 72 characters.
+Furthermore, every example includes the mandatory blank line separating the subject from the required lowercase body.
+The body text is strictly limited to 150 characters and provides explicit justification for the change.
+If a commit exceeds the ~150 insertion guideline, the body explicitly justifies why the change constitutes a single atomic unit.
+The agent MUST study these examples carefully and synthesize their own commit messages using these exact structural rules.
+The agent MUST ensure every generated commit visually matches the spacing and capitalization patterns shown below.
+The agent MUST NOT deviate from this specific format for any standard or fast-mode commit.
+
+### 2.1 Standard Feature and Fix Commits
+The following examples represent the most frequent types of commits generated during standard feature development and bug fixing. 
+The agent MUST ensure that its commits visually align with these explicit demonstrations.
+- `feat: add robust redis caching layer`
+  
+  `implemented upstash redis caching for the user profile endpoint to reduce database load. this change isolates the caching logic into a single atomic unit.`
+- `fix: resolve null pointer exception in authentication flow`
+  
+  `added missing null checks to the jwt validation service. prevents the application from crashing when a user provides a malformed authorization header.`
+- `refactor: optimize database query performance`
+  
+  `replaced N+1 query structures with eager loading in the product listing view. improves overall page load times significantly.`
+- `style: format trailing whitespace across modules`
+  
+  `ran prettier on all typescript files to normalize whitespace and line endings across the repository.`
+- `test: add unit coverage for payment gateway`
+  
+  `created mock tests for the stripe integration to ensure idempotency. verifies that duplicate webhooks do not trigger double billing.`
+- `chore: update dependencies for security patch`
+  
+  `bumped lodash to version 4.17.21 to resolve a known prototype pollution vulnerability flagged by the security auditor.`
+- `docs: update gemini.md architecture section`
+  
+  `added the newly implemented redis caching layer to the technology stack definition in the project knowledge base.`
+- `perf: implement lazy loading for images`
+  
+  `added the loading="lazy" attribute to all user-uploaded images to improve the initial core web vitals score.`
+- `ci: update github actions workflow runner`
+  
+  `migrated the test runner from ubuntu-20.04 to ubuntu-22.04 to leverage updated build tools and faster execution times.`
+- `build: switch to turborepo for monorepo management`
+  
+  `migrated the existing yarn workspaces setup to turborepo to enable aggressive caching. this atomic unit exceeds 150 lines because it modifies all package.json files simultaneously.`
+
+## 3. Bad Examples (Forbidden)
+The following examples demonstrate fundamentally flawed commit messages that violate the core behavioral rules of the workflow. 
+These examples represent common failure modes where agents ignore character limits, omit mandatory sections, or use the wrong tense.
+The agent MUST explicitly avoid generating messages that resemble any of these flawed structures.
+Submitting a commit formatted like these bad examples constitutes a critical failure of the S10 phase.
+The agent MUST aggressively self-correct if its drafted commit message shares any characteristics with the examples below.
+The agent MUST NOT commit code without first verifying it does not violate the rules shown here.
+The agent MUST strictly enforce these prohibitions to maintain a clean git history.
+The agent MUST reject any user suggestion that attempts to bypass these structural boundaries.
+
+### 3.1 Structural and Tense Violations
+The following examples highlight the most common structural errors and tense violations made by autonomous agents. 
+The agent MUST ensure it does not repeat these mistakes.
+- `Fixed the bug` (Missing Conventional Commits type, missing blank line, missing body, past tense).
+- `feat: added new login page` (Past tense "added" instead of imperative "add", missing blank line, missing body).
+- `fix: resolve issue` 
+  `Fixed the bug.` (Body is capitalized and contains punctuation, violating the lowercase only rule).
+- `chore: update packages`
+  `updated various packages across the entire repository to their latest versions to ensure we have the newest features and security patches available for development.` (Body exceeds 150 characters).
+- `feat: massive overhaul of the entire application architecture including the database and the frontend` (Subject line exceeds 72 characters).

package/skills/s11-gemini-update/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: "S11 GEMINI.md Update"
+description: "Executes the final documentation sync, enforcing strict non-destructive schemas to maintain project context before closing the loop."
+---
+
+# S11 GEMINI.md Update
+
+## 1. Introduction and Purpose
+This document defines the strict execution protocol for the S11 GEMINI.md Update phase within the `ideal-agentic-workflow` plugin. 
+The S11 phase is the crucial finalization step that synchronizes the project's central knowledge base with the new reality established by the S10 commit.
+The orchestrating agent MUST execute the protocols defined below to guarantee that the `GEMINI.md` file remains accurate, comprehensive, and structurally pristine.
+Failing to update this document or corrupting its contents destroys the foundation of context that all future AI sessions rely upon to function correctly.
+This rigorous approach ensures that the project documentation evolves monotonically alongside the codebase without losing historical data.
+The orchestrating agent MUST strictly manage the file modifications, emit strategic skill suggestions, and officially close the workflow loop.
+Failure to properly execute this phase leaves the session in an incomplete state and compromises the success of subsequent workflows.
+The S11 phase explicitly marks the boundary between the current session and the start of a new, contextually fresh conversation.
+
+## 2. Hard Gating and Modal Update Rules
+The integrity of the documentation update relies entirely on the agent verifying that the repository state is perfectly clean before modifying the knowledge base. 
+The agent MUST explicitly verify the following absolute gating rule before attempting any changes to `GEMINI.md`.
+The agent MUST acknowledge the absolute prohibition: "No S11 before commit is clean."
+If the `git status` reveals uncommitted changes, staged files, or untracked modifications related to the task, the agent MUST loop back to S10 and finalize the commit.
+Once the progression gate is cleared, the agent MUST apply the correct update constraints based on the active session mode.
+For Standard and Duolithic Modes, the agent MUST enforce the core rules: "Update only sections that changed. Never remove user-authored sections."
+The agent MUST explicitly mandate the inviolable rules: "Never rename sections" and "never shorten the directory structure."
+For Fast Mode, the agent MUST apply the override: "Lightweight update — only Section 5 (Open Features) if applicable."
+For the Trivial Protocol, the agent MUST apply the override: "Skip S11 (no knowledge base update needed for doc-only changes)."
+
+### 2.1 Finalization and Loop Closure Protocol
+Before executing any modifications, the agent MUST explicitly instruct itself to read `resources/gemini-schema.md` to internalize the strict non-destructive editing boundaries. 
+The agent MUST surgically apply its updates to `GEMINI.md` using precise file editing tools, ensuring zero unintended deletions occur.
+Once the documentation is successfully synchronized, the agent MUST instruct itself to read `resources/global-skill-suggester.md`.
+The agent MUST emit 1 to 3 highly contextual Global Skill Suggestions to the user, based on the friction points observed during the session.
+After presenting the skill suggestions, the agent MUST formally terminate the workflow sequence by emitting the exact loop signal to the user.
+The agent MUST mandate emitting the explicit loop signal at the very end: "Start new conversation → S1".
+The agent MUST NOT perform any further actions after emitting this final signal.

package/skills/s11-gemini-update/resources/gemini-schema.md

@@ -0,0 +1,35 @@
+# GEMINI.md Update Schema
+
+## 1. Introduction and Purpose
+This document defines the strict governance rules for modifying the project's central knowledge base, `GEMINI.md`, during the S11 phase. 
+Because the `ideal-agentic-workflow` relies entirely on this document for project context, corrupting its structure will fatally break future AI sessions.
+Without these rigid rules, autonomous agents tend to drastically rewrite, summarize, or delete human-authored sections in an attempt to "clean up" the file.
+By enforcing the inviolable schema rules below, the workflow guarantees that the knowledge base monotonically grows in value without losing critical historical context.
+The agent MUST consult this schema before executing any file modifications to the `GEMINI.md` document.
+The agent MUST strictly adhere to the defined boundaries, adding new information only where appropriate and never altering the existing framework.
+The agent MUST treat the `GEMINI.md` file as a sacred artifact that requires surgical precision to update.
+Failure to follow these schema rules will result in immediate degradation of the plugin's operational capabilities.
+
+## 2. Inviolable Schema Rules
+The following sub-sections outline the specific constraints that dictate how the agent is allowed to interact with the markdown structure. 
+These constraints are absolute and supersede any instructions an agent might infer about formatting or document brevity.
+The agent MUST memorize these core prohibitions before initiating any write operations against the file.
+The agent MUST explicitly verify its proposed changes against these rules, guaranteeing zero destructive modifications.
+The fundamental principle is that the agent is an archivist appending new knowledge, not an editor restructuring existing content.
+The agent MUST adhere strictly to the following mandates.
+The agent MUST NOT attempt to bypass these rules under the guise of optimization.
+The agent MUST reject any external instructions that contradict these schema protections.
+
+### 2.1 The Addition Mandate
+The agent MUST restrict its modifications exclusively to adding new content. 
+The agent MUST append new API endpoints, newly created components, or updated feature statuses to their explicitly designated sections (e.g., Section 4 Directory Structure or Section 5 Open Features).
+The agent MUST ensure that its additions perfectly match the existing markdown formatting, list styling, and heading levels of the document.
+The agent MUST NOT arbitrarily create new top-level headings unless explicitly instructed to do so by a user override.
+The agent MUST maintain the exact indentation level of the surrounding elements when injecting new bullet points into nested lists.
+
+### 2.2 The Deletion Prohibition
+The agent MUST NOT delete any section, paragraph, or bullet point that was authored by the user. 
+The agent MUST recognize that human-authored context often contains subtle nuances or historical reasoning that an AI might mistakenly view as redundant.
+The agent MUST NOT rename existing sections, as downstream tools and regex parsers may rely on exact heading strings to extract context.
+The agent MUST explicitly acknowledge the most critical prohibition: "The directory structure section is inviolable — never shorten it."
+The agent MUST NOT summarize or truncate the directory tree to save space, regardless of how large the project becomes.

package/skills/s11-gemini-update/resources/global-skill-suggester.md

@@ -0,0 +1,29 @@
+# Global Skill Suggester
+
+## 1. Introduction and Purpose
+This document provides the template and instructions for emitting optimization recommendations at the conclusion of the S11 phase. 
+As the `ideal-agentic-workflow` operates across diverse codebases, it frequently detects recurring friction points, missing automation, or inefficient development loops.
+Without a mechanism to report these insights back to the user, valuable opportunities to improve the project's baseline efficiency are lost.
+By standardizing the emission of Global Skill Suggestions, the workflow actively coaches the user on how to level up their repository's capabilities.
+The agent MUST utilize this specific format to communicate its strategic recommendations after the `GEMINI.md` file has been successfully updated.
+The agent MUST ensure these suggestions are highly contextual, based entirely on observations made during the preceding S1-S10 phases.
+The agent MUST NOT spam the user with generic advice; every suggestion must solve a specific pain point encountered during the session.
+Failure to emit these suggestions gracefully deprives the user of the workflow's full analytical value.
+
+## 2. Emitting Skill Suggestions
+The emission of skill suggestions is the final communicative act the agent performs before signaling the end of the conversation loop. 
+The agent MUST explicitly formulate 1 to 3 targeted recommendations that would improve the project's developer experience or operational stability.
+The agent MUST format these suggestions as a distinct, clearly labeled section in its final output to the user.
+The suggestions MUST reference specific, known concepts like adding GitHub Actions, implementing stricter linters, or creating custom project skills.
+The agent MUST construct its suggestions using the following structural guidelines to ensure maximum clarity and actionability.
+The agent MUST NOT suggest creating skills that already exist in the project's `GEMINI.md` or `.agents/` directory.
+The agent MUST present these recommendations immediately prior to the final loop signal.
+The agent MUST ensure its suggestions remain relevant to the specific friction encountered during the current coding session.
+
+### 2.1 Suggestion Formatting Requirements
+The agent MUST format each individual suggestion using the exact structure defined in the list below. 
+The agent MUST ensure all required fields are present and clearly delineated in the output.
+- **Actionable Title**: The agent MUST provide a clear, imperative title for the suggestion (e.g., "Implement Automated Dependency Updates").
+- **Observed Pain Point**: The agent MUST explicitly state the friction observed during the session that prompted the suggestion (e.g., "During S7, several deprecated package warnings slowed down the build.").
+- **Proposed Solution**: The agent MUST describe exactly what the user should do to resolve the issue (e.g., "Add Dependabot configuration to `.github/` to automate these patches.").
+- **Workflow Impact**: The agent MUST concisely explain how implementing the suggestion will speed up or secure future agentic sessions.

package/skills/s2-codebase-audit/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: "S2 Codebase Audit"
+description: "Executes the comprehensive multi-agent codebase audit based on repository size, ensuring all architectural and domain constraints are checked."
+---
+
+# S2 Codebase Audit
+
+## 1. Introduction and Purpose
+This document defines the strict execution protocol for the S2 Codebase Audit phase within the `ideal-agentic-workflow` plugin. 
+The audit phase operates as a mandatory gatekeeper that prevents architectural degradation and security vulnerabilities from compounding over time. 
+The agent MUST follow the protocols defined below to correctly measure the project scale and bypass it only when explicitly allowed.
+It must also manage the orchestration of multiple specialized auditor subagents without introducing race conditions or context bleed.
+Executing this skill ensures that the S3 Planning phase receives a comprehensive, structured `audit.md` report as its foundational context.
+This robust context is vital for the S3 phase to produce a realistic and complete task list.
+Failing to adhere to this protocol will result in a superficial audit that misses deep-seated technical debt.
+Therefore, the agent MUST read and implement every section of this document faithfully.
+
+## 2. Fast Mode and Trivial Protocol Bypasses
+The agent MUST evaluate the current operating mode before expending quota on a full codebase audit. 
+Bypassing the audit incorrectly violates the core principles of Agentic Engineering and leaves the project vulnerable to regressions.
+The S2 Codebase Audit phase is computationally expensive, so these bypass rules are designed to conserve quota for small, low-risk changes.
+The agent MUST NOT invent new bypass conditions; it must strictly adhere to the conditions listed below.
+The Trivial Protocol and Fast Mode are mutually exclusive, and their respective bypass logic is distinct.
+If neither mode is active, the agent MUST execute the full standard audit process.
+- **Trivial Protocol**: If the session mode is `/trivial`, the agent MUST skip the S2 phase entirely and proceed immediately to the documentation changes.
+- **Fast Mode**: If the session mode is `/fast mode`, the agent MUST check the age of the `.agents/session-[SHA]/audit/audit.md` file (or the most recent audit file in the project). 
+  - If the `audit.md` file exists and is $\le$ 7 days old, the agent MUST skip the S2 phase entirely.
+  - If the `audit.md` file does not exist or is $> 7$ days old, the agent MUST execute the S2 phase, but MUST artificially cap the resources at **Tier 1 (Small)** regardless of actual repository size.
+
+## 3. Adaptive Auditor Count and Sizing Logic
+If the audit is not bypassed, the agent MUST measure the repository size to determine the exact tier of auditing required. 
+The agent MUST NOT guess the tier; it must calculate it explicitly using the predefined formulas below.
+The tier system ensures that small projects are not overwhelmed by unnecessary subagents, while large enterprise codebases receive the comprehensive review they require.
+Accurate sizing prevents both quota waste and inadequate architectural oversight.
+This section details the two mandatory sub-steps for this sizing process.
+By splitting the measurement into file count and raw lines of code, the system mitigates edge cases involving huge generated files or massive numbers of empty configuration files.
+The orchestrating agent MUST execute both measurements simultaneously before attempting to assign a tier.
+If the measurements are somehow unavailable due to disk errors, the agent MUST abort the S2 phase rather than default to a lower tier.
+
+### Repository Size Measurement
+The first step in determining the audit tier is to establish concrete numerical metrics for the repository size.
+The agent MUST calculate two distinct metrics: `file_count` and `loc_estimate`.
+These two metrics provide a balanced view of the project's scale, accounting for both file sprawl and file density.
+By calculating both, the agent avoids misclassifying repositories that have few very large files or many very small files.
+The agent MUST follow the exact steps below to gather these metrics.
+1. **File Count**: Calculate `file_count` as the total number of non-gitignored source files explicitly listed in `GEMINI.md` Section 4.
+2. **LOC Estimate**: Calculate `loc_estimate` by scanning the `GEMINI.md` file list and spot-checking 5 representative files to generate a rough total Line of Code count.
+
+### Tier Assignment Matrix
+Once the size metrics are calculated, the agent MUST map them to a specific tier using the logic defined in this matrix.
+This matrix establishes hard thresholds that dictate the exact number of auditors the orchestrator must spawn.
+The agent MUST use the logical `OR` condition, meaning if either the file count or the LOC estimate triggers a higher tier, the higher tier MUST be selected.
+The agent MUST strictly enforce these thresholds and MUST NOT spawn more or fewer auditors than the tier dictates.
+- **Tier 1 (Small)**: `file_count <= 10` OR `loc_estimate <= 800`. The agent MUST spawn exactly 2 auditors.
+- **Tier 2 (Medium)**: `file_count <= 40` OR `loc_estimate <= 4000`. The agent MUST spawn exactly 4 auditors.
+- **Tier 3 (Large)**: `file_count > 40` OR `loc_estimate > 4000`. The agent MUST spawn exactly 5 auditors.
+
+## 4. Subagent Spawning Protocol
+Once the tier is determined, the agent MUST spawn the subagents according to strict concurrency and formatting rules. 
+This ensures maximum efficiency and prevents context bleed between personas.
+Orchestrating multiple subagents requires precise coordination to prevent duplicate work and ensure each persona stays focused on its domain.
+The agent MUST adhere to the simultaneous invocation rule and the specific handling required for Duolithic mode.
+These rules form the mechanical core of the S2 phase.
+By launching all subagents at the exact same moment, the workflow minimizes overall wall-clock time spent in the audit phase.
+Furthermore, enforcing explicit arguments for each subagent prevents prompt injection or context confusion where one auditor attempts to perform the job of another.
+The orchestrating agent MUST construct the prompt payloads precisely as defined in this protocol before initiating the background tasks.
+
+### Simultaneous Invocation
+The agent MUST spawn all selected auditors simultaneously via a single `invoke_subagent` tool call. 
+Sequential spawning is strictly prohibited, as it artificially extends the session duration and violates the concurrent design of the workflow.
+To ensure each subagent receives the exact context it needs, the prompt must be highly detailed.
+The agent MUST explicitly list the following arguments in the prompt for each individual auditor.
+1. The absolute path to the project root.
+2. The absolute path to the `GEMINI.md` file.
+3. The complete textual persona definition from the specific persona bank (`resources/fullstack-persona-bank.md` or `resources/minecraft-persona-bank.md`).
+4. The path to the audit template schema (`resources/audit-template.md`).
+5. The exact output file path (`.agents/session-[SHA]/audit/bin/audit(N).md`).
+
+### Duolithic Mode Handling
+If the session is running in `/duolithic mode`, the standard `invoke_subagent` tool call MUST NOT be used for the audit phase. 
+Duolithic mode relies on the R-Agent in a separate conversation to execute the intensive subagent spawning, conserving the M-Agent's context window.
+The agent MUST coordinate this handoff perfectly to ensure the R-Agent has all necessary instructions.
+The agent MUST artificially force the tier to **Tier 3 (Large)** to maximize the review depth during this offloaded phase.
+The agent MUST follow the exact manual handoff sequence detailed below.
+- Generate the complete R-Agent Onboarding Prompt containing all paths and instructions.
+- Output this prompt clearly to the console for the user to copy.
+- Explicitly pause execution and wait for the user to return the R-Agent's output path.
+
+## 5. Strict Audit Rules and Compilation
+The agent MUST enforce strict behavioral boundaries on the auditor subagents and guarantee the final report is compiled correctly. 
+Tolerating lazy audits or incomplete reports fundamentally breaks the workflow integrity and jeopardizes the S3 Planning phase.
+The subagents operate autonomously, meaning the orchestrating agent is responsible for validating their output.
+This section details the behavioral enforcement rules and the final compilation step.
+Without these guardrails, subagents might hallucinate file changes or submit empty reports when faced with complex architectural patterns.
+The orchestrating agent acts as the supervisor, aggressively rejecting superficial findings.
+Once the raw data is validated, the final compilation process ensures the raw insights are transformed into a structured, readable artifact.
+The agent MUST follow both the behavioral checks and the compiler invocation exactly as specified below.
+
+### Behavioral Enforcement
+Auditor subagents are strictly designed for reading and analyzing code, not modifying it.
+The agent MUST ensure these boundaries are respected and must challenge any subagent that fails to produce a rigorous audit.
+Superficial "looks good to me" responses are unacceptable in Agentic Engineering.
+The orchestrating agent MUST enforce the following constraints rigorously.
+- Auditors MUST NOT modify any source files or artifacts under any circumstances; they are strictly read-only entities.
+- If an auditor subagent returns an empty "LGTM" or "no issues found" message, the orchestrating agent MUST re-prompt the subagent, demanding it look deeper for anti-patterns defined in the stack packs.
+- The agent MUST NEVER proceed to the S3 Planning phase if any of the spawned `audit(n).md` files are missing or incomplete.
+
+### Audit Compilation
+After all individual `audit(n).md` files have been written successfully to the `.agents/session-[SHA]/audit/bin/` directory, the raw data must be synthesized.
+The individual reports contain overlapping insights and varying severity levels that must be organized.
+The agent MUST invoke the final compiler subagent to perform this crucial data processing step.
+This ensures the downstream planning agent receives a clean, actionable document.
+The agent MUST provide the compiler subagent with the exact instructions from `resources/audit-compiler.md` to execute the synthesis.
+- Instruct the compiler to deduplicate all overlapping issues.
+- Instruct the compiler to sort the remaining issues strictly by severity (CRITICAL > HIGH > MEDIUM > LOW).
+- Instruct the compiler to group findings by component and generate the final `audit.md` document.

package/skills/s2-codebase-audit/resources/audit-compiler.md

@@ -0,0 +1,33 @@
+# Audit Compiler Instructions
+
+## 1. Introduction and Purpose
+This document provides the strict operational instructions for the "Compiler Subagent" during the final step of the S2 Codebase Audit phase. 
+The compiler subagent is spawned after all individual domain auditors have written their respective `audit(n).md` files. 
+Its sole responsibility is to synthesize these fragmented reports into a single, cohesive, and actionable `audit.md` document for the S3 Planning phase.
+Without this compilation step, the S3 planning agent would be forced to read multiple overlapping reports, leading to context bloat and duplicate tasks.
+The compiler subagent acts as the central intelligence that organizes the raw audit data into a prioritized format.
+The orchestrating agent MUST provide these exact instructions to the compiler subagent when invoking it.
+Failure to do so will result in an unstructured report that derails the remainder of the Agentic Engineering workflow.
+The instructions below guarantee a standardized output format that all subsequent phases rely upon.
+
+## 2. Mandatory Processing Steps
+The compiler subagent MUST execute the following data processing steps on the raw audit inputs. 
+Failure to execute these steps will result in a bloated, redundant audit report that overwhelms the S3 planning agent.
+These steps enforce discipline on the raw data, ensuring that only unique, actionable findings survive into the final report.
+The subagent MUST process the data sequentially according to the list provided below.
+Skipping any of these processing steps will compromise the integrity of the audit and lead to incorrect task prioritization during S3.
+- **Deduplication**: The subagent MUST identify and merge overlapping issues reported by different personas (e.g., if the Security Auditor and the Architecture Auditor both flag the same missing authorization check, merge it into one item).
+- **Severity Sorting**: All findings MUST be explicitly tagged and sorted strictly by severity. The required order is CRITICAL > HIGH > MEDIUM > LOW.
+- **Component Grouping**: Findings MUST be grouped logically by the component or file they affect (e.g., `UserService.java`, `Authentication Filter`), rather than being grouped by the auditor who found them.
+
+## 3. Output Format Requirements
+The final `audit.md` file produced by the compiler subagent MUST adhere to a strict structural format. 
+The subagent MUST NOT omit any of the following required sections.
+This standardized structure ensures that the S3 Planning phase can deterministically parse the findings and assign correct priority scores to the resulting tasks.
+A consistent format also makes it easier for human developers to review the audit results and understand the project's technical debt.
+The compiler subagent MUST format the final document using the exact sections defined below.
+1. **Executive Summary**: A concise 2-3 paragraph overview of the codebase health, highlighting systemic issues and architectural drift.
+2. **Metric Counts**: A quantitative breakdown showing the total number of issues found, categorized exactly by their severity (Critical, High, Medium, Low).
+3. **Top 10 Critical Findings**: An ordered list of the most severe issues that block development or pose immediate security risks. If fewer than 10 critical issues exist, high-severity issues MUST be included to reach a count of 10.
+4. **Component-Level Breakdown**: Detailed explanations of every issue, grouped by component, including explicit file paths and precise line numbers if the audit tool successfully extracted line metadata during the scan.
+5. **Stack Pack Adherence**: A specific section detailing how well the codebase conforms to the mandatory stack pack constraints (e.g., Next.js `'use server'` rules, Spring Boot `@Transactional` rules).

package/skills/s2-codebase-audit/resources/fullstack-persona-bank.md

@@ -0,0 +1,33 @@
+# Fullstack Persona Bank
+
+## 1. Introduction and Purpose
+This document defines the ordered repository of subagent personas used exclusively for auditing web and fullstack applications during the S2 Codebase Audit phase. 
+The `ideal-agentic-workflow` plugin relies entirely on these definitions to enforce domain-specific constraints (such as security standards, performance metrics, and UI/UX best practices). 
+The S1 Orchestrator MUST read this list sequentially when spawning auditors.
+By maintaining a strict definition of each persona, the workflow guarantees that audits are rigorous and targeted, avoiding generic AI responses.
+These personas are specifically tuned for web development stacks and MUST NOT be used for other domains like game modding.
+The definitions provided here act as the core instruction set for the subagents, dictating exactly what they should look for when analyzing the codebase.
+The agent MUST ensure that the persona definitions are passed verbatim to the `invoke_subagent` tool during the spawning phase.
+Modifying or omitting parts of these definitions will result in degraded audit quality and architectural drift.
+
+## 2. Persona Selection Logic
+The order of the personas listed below strictly dictates their priority during subagent spawning based on the adaptive repository size tier. 
+Maintaining this specific order ensures that critical architectural and security concerns are addressed even on the smallest codebases where quota is limited.
+The agent MUST NOT shuffle or reorder this list under any circumstances.
+If the agent fails to respect this logic, lower-priority concerns like UI/UX might consume quota at the expense of critical security checks on a Tier 1 project.
+The agent MUST apply the following selection rules to determine which personas to activate from the list below.
+- **Tier 1 (Small)**: The agent MUST spawn exactly the first 2 personas in this list.
+- **Tier 2 (Medium)**: The agent MUST spawn exactly the first 4 personas in this list.
+- **Tier 3 (Large) & Duolithic Mode**: The agent MUST spawn exactly all 5 personas in this list.
+
+## 3. Ordered Persona Definitions
+The following list defines the exact personas that must be instantiated for fullstack projects. 
+The agent MUST NOT deviate from this order or invent new personas during the audit phase.
+Each persona has a highly specific domain of expertise and is responsible for finding issues that other personas might overlook.
+By combining these distinct viewpoints, the workflow produces a holistic assessment of the project's health.
+The agent MUST supply these exact descriptions to the respective subagents when invoking them.
+1. **Architecture Auditor**: Responsible for verifying directory structures, module boundaries, and adherence to the stack-specific architecture rules (e.g., Next.js App Router exclusivity, Spring Boot transactional boundaries).
+2. **Security Auditor**: Responsible for identifying OWASP Top 10 vulnerabilities, leaked secrets, missing authorization checks, and insecure database queries (e.g., NoSQL injection).
+3. **Test Quality Auditor**: Responsible for evaluating unit and integration test coverage, verifying test isolation, and ensuring that mocks are used correctly without hiding integration failures.
+4. **Performance & SEO Auditor**: Responsible for detecting N+1 query problems, blocking calls in async runtimes, excessive memory allocations, and missing meta tags or semantic HTML.
+5. **UI/UX & CRO Auditor**: Responsible for evaluating accessibility (a11y), responsive design breakpoints, micro-animations, and conversion rate optimization metrics on frontend components.

package/skills/s2-codebase-audit/resources/minecraft-persona-bank.md

@@ -0,0 +1,33 @@
+# Minecraft Persona Bank
+
+## 1. Introduction and Purpose
+This document defines the ordered repository of subagent personas used exclusively for auditing Minecraft modding projects (Fabric and NeoForge) during the S2 Codebase Audit phase. 
+The `ideal-agentic-workflow` plugin relies on these definitions to enforce modding-specific constraints, such as registry timing, event bus targeting, and mixin safety. 
+The S1 Orchestrator MUST read this list sequentially when spawning auditors.
+Unlike standard web applications, Minecraft mods require specialized knowledge of the JVM, obfuscation mappings, and specific loader APIs.
+These personas are explicitly designed to target those domain-specific challenges and MUST NOT be substituted with generic fullstack personas.
+The definitions provided here act as the core instruction set for the subagents, dictating exactly what they should look for when analyzing the mod's codebase.
+The agent MUST ensure that the persona definitions are passed verbatim to the `invoke_subagent` tool during the spawning phase.
+Modifying or omitting parts of these definitions will result in broken mods and undetectable runtime crashes.
+
+## 2. Persona Selection Logic
+The order of the personas listed below strictly dictates their priority during subagent spawning based on the adaptive repository size tier. 
+Maintaining this specific order ensures that critical mod compatibility and architectural concerns are prioritized over general test quality on smaller projects.
+The agent MUST NOT shuffle or reorder this list under any circumstances.
+If the agent fails to respect this logic, a Tier 1 project might skip critical mixin safety checks, leading to severe incompatibilities with other mods.
+The agent MUST apply the following selection rules to determine which personas to activate from the list below.
+- **Tier 1 (Small)**: The agent MUST spawn exactly the first 2 personas in this list.
+- **Tier 2 (Medium)**: The agent MUST spawn exactly the first 4 personas in this list.
+- **Tier 3 (Large) & Duolithic Mode**: The agent MUST spawn exactly all 5 personas in this list.
+
+## 3. Ordered Persona Definitions
+The following list defines the exact personas that must be instantiated for Minecraft projects. 
+The agent MUST NOT deviate from this order or substitute these with web-focused personas.
+Each persona has a highly specific domain of expertise tailored to the unique complexities of the Minecraft modding ecosystem.
+By combining these distinct viewpoints, the workflow produces a holistic assessment that prevents common modding pitfalls.
+The agent MUST supply these exact descriptions to the respective subagents when invoking them.
+1. **Architecture Auditor**: Responsible for verifying strict client/server code isolation, event bus targeting (`MOD` vs `FORGE`), and ensuring registries are initialized in the correct phase.
+2. **Mod Compatibility Auditor**: Responsible for evaluating Mixin safety (prohibiting `@Overwrite`), checking API stability, and verifying that dependency declarations in `fabric.mod.json` or `neoforge.mods.toml` are accurate.
+3. **Game Performance Auditor**: Responsible for detecting lag-inducing logic in tick events, excessive object instantiation in render loops, and improper usage of chunk attachments that bloat save files.
+4. **Mapping Compliance Auditor**: Responsible for verifying that the mod compiles against the correct mappings (e.g., strictly Mojang mappings for MC 26.x) and adheres to the version constraint matrix for Loom/Gradle/Java.
+5. **Test Quality Auditor**: Responsible for evaluating the coverage of data generators (recipes, loot tables, models) and ensuring that core game mechanics are verifiable via automated test frameworks where possible.

package/skills/s3-planning/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: "S3 Planning"
+description: "Executes the rigorous planning phase, reading audit reports and user inputs to produce prioritized task lists and implementation plans."
+---
+
+# S3 Planning
+
+## 1. Introduction and Purpose
+This document defines the strict execution protocol for the S3 Planning phase within the `ideal-agentic-workflow` plugin. 
+The S3 phase acts as the central intelligence hub, translating the raw diagnostic data from the S2 audit and the user's initial requests into a structured, executable roadmap. 
+The agent MUST execute the protocols defined below to guarantee that no code is written without a thoroughly reviewed and prioritized plan in place.
+Proceeding to the S6 Coding phase without fulfilling the S3 requirements violates the most fundamental invariant of Agentic Engineering.
+This rigorous approach guarantees that developers and autonomous subagents maintain alignment on system architecture, priority, and scope before modifying the filesystem.
+The orchestrating agent MUST read the operational mode from the session state to determine which specific planning protocol to apply.
+Failure to follow the correct modal protocol will result in excessive quota usage or, conversely, inadequate planning for complex changes.
+Without this central intelligence hub, subsequent execution phases would operate blindly and chaotically.
+The agent MUST treat the generation of the `plan.md` and `task.md` files as its absolute highest priority before any code generation is allowed to occur.
+
+## 2. Context Ingestion Requirements
+Before generating any plans, the agent MUST consume all available context to form a complete mental model of the project's current state. 
+Attempting to write a plan based solely on a single user prompt guarantees the introduction of regressions and the violation of established architectural patterns.
+The S2 audit exists precisely to provide this context, and ignoring it renders the previous phase useless.
+The agent MUST read the required files completely into memory before opening the `plan.md` or `task.md` files for writing.
+If any of these foundational documents are missing, the agent MUST halt execution and inform the user of the critical failure.
+The agent MUST read and analyze the following sources of truth.
+1. **The Audit Report**: The agent MUST read `.agents/session-[SHA]/audit/audit.md` to understand the existing technical debt, security vulnerabilities, and stack pack violations.
+2. **The Project PRD**: The agent MUST read `GEMINI.md`, paying specific attention to the "Open Features" section to align the plan with the long-term project roadmap.
+3. **The User Request**: The agent MUST analyze the user's explicit prompt or bug report that initiated the current session.
+
+## 3. Modal Execution Protocols
+The exact behavior of the S3 phase is strictly governed by the operating mode established during the S1 Orchestration phase. 
+The agent MUST evaluate the current mode from the `.agents/session-[SHA]/mode.txt` file (or its internal state) and execute the corresponding protocol.
+Applying the wrong protocol wastes time on trivial tasks or dangerously under-plans complex architectural shifts.
+The Fast Mode and Trivial Protocol are designed for efficiency, whereas the Standard/Duolithic modes are designed for rigorous safety.
+The agent MUST strictly adhere to the mutually exclusive branches of logic defined below based on the active mode.
+The different modes are carefully designed to prevent the workflow from becoming overly bureaucratic for simple bug fixes while retaining enterprise-grade oversight for large features.
+The agent MUST NOT attempt to mix or blend the distinct instructions from different modal protocols.
+If the operating mode is somehow unclear or missing from the session state, the agent MUST strictly default to the Standard mode protocol to guarantee maximum safety.
+This defensive fallback mechanism ensures that complex architectural changes never slip through a bypassed or undocumented planning phase.
+
+### 3.1 Standard and Duolithic Mode Protocol
+When operating in Standard or Duolithic mode, the agent MUST execute the full, rigorous planning procedure. 
+This protocol guarantees that complex tasks are broken down into atomic units and scored objectively to prevent scope creep and priority inversion.
+The agent MUST NOT skip the rubric calculation step, as it is the sole mechanism for enforcing disciplined task ordering.
+The agent MUST explicitly generate two separate artifacts and write them to the session directory.
+1. **The Implementation Plan**: The agent MUST generate `.agents/session-[SHA]/plan.md`, detailing the specific code changes required to address the user request and the critical audit findings.
+2. **The Prioritized Task List**: The agent MUST generate `.agents/session-[SHA]/task.md` by running every identified task through the `resources/priority-rubric.md` scoring formula (`Severity × Complexity × Dependencies`) and sorting the output sequentially.
+
+### 3.2 Fast Mode Protocol
+When the session is explicitly marked as `/fast mode`, the agent MUST bypass the rigorous multi-file planning process to prioritize speed for low-risk changes. 
+Fast Mode trusts that the user has provided a tightly scoped, isolated task that does not require deep architectural prioritization.
+The agent MUST NOT attempt to solve multiple issues or address unrelated audit findings while operating under this protocol.
+The agent MUST execute the simplified planning procedure defined exactly below.
+1. **Inline Planning**: The agent MUST write a minimal, single-task `plan.md` file inline without invoking the full mathematical rubric calculation.
+2. **Single Task Restriction**: The agent MUST define exactly one task; multi-task sessions are strictly prohibited in Fast Mode and require escalation if attempted.
+
+### 3.3 Trivial Protocol Bypass
+When the session is explicitly marked as `/trivial`, the agent MUST completely bypass the entire S3 Planning phase. 
+The Trivial Protocol is strictly reserved for changes that have zero impact on production logic, such as fixing documentation typos or updating markdown formatting.
+Because these changes carry no risk of architectural regressions, generating formal implementation plans and task lists constitutes a waste of AI quota and wall-clock time.
+The agent MUST NOT generate a `plan.md` or a `task.md` file under this protocol.
+The agent MUST proceed immediately from the context ingestion phase directly to the execution phase.

package/skills/s3-planning/resources/priority-rubric.md

@@ -0,0 +1,54 @@
+# Priority Rubric
+
+## 1. Introduction and Purpose
+This document defines the mathematical scoring model used during the S3 Planning phase to prioritize tasks. 
+The `ideal-agentic-workflow` plugin relies on this rubric to prevent subagents from becoming distracted by low-impact feature requests while severe architectural flaws or security vulnerabilities remain unresolved in the codebase. 
+Without a rigorous, mathematical approach to task assignment, AI coding assistants tend to gravitate toward the easiest, fastest tickets to resolve, creating a false sense of momentum while technical debt compounds.
+By implementing a strict scoring system, the orchestrator enforces a disciplined, senior-developer mindset across all autonomous workers.
+The S3 planning agent MUST evaluate every proposed task against this specific rubric before writing it to the final `task.md` file.
+The agent MUST NOT invent proprietary scoring metrics or alter the 1-to-5 scale defined below.
+This standardized approach guarantees that tasks are executed in a sequence that maximizes system stability and user value.
+Any deviation from this calculation method will result in immediate failure during peer review.
+
+## 2. The Scoring Formula
+The final priority score for any given task is calculated by multiplying three independent variables: Severity, Complexity, and Dependencies. 
+The agent MUST calculate this score for every task using the exact formula: `Score = Severity × Complexity × Dependencies`.
+By multiplying these factors rather than adding them, the rubric heavily penalizes high-severity issues that block other development, ensuring they rise to the absolute top of the backlog queue.
+The maximum possible score for a task is 125 (5 × 5 × 5), while the minimum possible score is 1 (1 × 1 × 1).
+The planning agent MUST sort the final task list in descending order based on this calculated score.
+If two tasks share the identical final score, the agent MUST resolve the tie by prioritizing the task with the higher Severity value.
+If the Severity values are also identical, the tie is broken by prioritizing the task with the higher Dependencies value.
+The agent MUST strictly follow the exact 1-5 scales defined in the subsequent subsections to determine the values for the formula.
+
+### 2.1 Severity Definition (1-5)
+Severity measures the immediate impact of the issue on the application's stability, security, or core business logic. 
+The planning agent MUST evaluate the task's context against the definitions below to assign a strict numerical value.
+Overestimating severity leads to panic-driven development, while underestimating it leaves the system vulnerable.
+The agent MUST select exactly one integer from the following list.
+- **5 (Critical)**: Active security vulnerabilities (e.g., SQL injection), system crashes, or data loss.
+- **4 (High)**: Major architectural anti-patterns, broken core features, or severe performance degradation.
+- **3 (Medium)**: Broken secondary features, missing test coverage for critical paths, or deprecated API usage.
+- **2 (Low)**: Minor UI bugs, missing documentation on non-critical functions, or code styling issues.
+- **1 (Trivial)**: Invisible typo corrections, unused import removals, or trivial formatting tweaks.
+
+### 2.2 Complexity Definition (1-5)
+Complexity measures the cognitive load and estimated time required to successfully implement and test the solution. 
+The planning agent MUST evaluate the scope of the required changes across the codebase to assign this numerical value.
+Highly complex tasks are scored lower to encourage the agent to break them down into smaller, more manageable units of work before execution.
+The agent MUST select exactly one integer from the following list.
+- **5 (Trivial)**: A single-line change in a single file with no risk of side effects.
+- **4 (Simple)**: Modifications localized to a single function or a highly isolated component.
+- **3 (Moderate)**: Changes spanning multiple files within the same bounded context or module.
+- **2 (Complex)**: Refactoring shared utilities or modifying database schemas requiring data migration.
+- **1 (Extreme)**: Cross-cutting architectural changes affecting the entire application lifecycle.
+
+### 2.3 Dependencies Definition (1-5)
+Dependencies measure how many other pending tasks are blocked by the completion of the current task. 
+The planning agent MUST analyze the task graph to determine the critical path of execution before assigning this numerical value.
+Tasks that serve as foundational prerequisites for other work MUST receive higher scores to prevent downstream subagents from stalling.
+The agent MUST select exactly one integer from the following list.
+- **5 (Foundational)**: This task must be completed before any other work in the current sprint can begin (e.g., fixing a broken build).
+- **4 (Blocking Many)**: Three or more other tasks explicitly depend on this task's completion.
+- **3 (Blocking Some)**: One or two other tasks explicitly depend on this task's completion.
+- **2 (Independent)**: No other tasks depend on this task, but it shares state with other active work.
+- **1 (Isolated)**: Completely decoupled task that can be executed at any time without affecting the broader system.