ideal-agentic-workflow 1.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,16 @@
+{
+  "name": "ideal-agentic-workflow",
+  "version": "1.1.0",
+  "description": "Enforces S1–S11 Agentic Engineering: audit-first, plan-reviewed, code-verified, commit-disciplined development.",
+  "author": {
+    "name": "RachitSWE",
+    "url": "https://github.com/RachitSWE"
+  },
+  "keywords": [
+    "workflow",
+    "audit",
+    "agentic-engineering",
+    "review-driven",
+    "tdd"
+  ]
+}

package/AGENTS.md

@@ -0,0 +1,113 @@
+# Agent Behavioral Rules
+
+This document defines the strict behavioral constraints for any AI agent operating within the `ideal-agentic-workflow` plugin. 
+
+These rules MUST be loaded on every session. 
+
+They exist to prevent "Vibe Coding" and enforce disciplined Agentic Engineering. 
+
+Agents MUST NOT treat these rules as suggestions; they are absolute invariants. 
+
+Any violation of these rules breaks the fundamental integrity of the workflow.
+
+The reader of this document is the AI agent executing the session.
+
+These rules govern the entire lifecycle of the S1-S11 process.
+
+They guarantee that no code is committed without proper planning, testing, and review.
+
+## Workflow Invariants
+
+The following rules govern the sequence of operations within the workflow. 
+
+They ensure that no step is skipped and that prerequisites are strictly met. 
+
+Skipping these steps leads to unreviewed code and corrupted session state.
+
+We MUST enforce these invariants to maintain the workflow's integrity.
+
+- NEVER write production code before plan.md exists AND is in LGTM status from S4.
+- NEVER invoke S8 code review if any automated test is failing.
+- NEVER write a review file yourself. Review must come from real subagents or R-Agent.
+- NEVER proceed to S10 if any task in task.md is not [x].
+- ALWAYS read GEMINI.md in full before reading any source file.
+- ALWAYS initialize .agents/session-SHA/ before starting S2.
+
+## File System Rules
+
+These constraints dictate where the agent is allowed to write files. 
+
+They prevent the project root from being cluttered with temporary artifacts. 
+
+They also protect the user's host system from unintended modifications.
+
+We MUST strictly isolate all agent-generated state to the session directory.
+
+This isolation ensures that a failed workflow session does not leave the repository in an inconsistent state.
+
+- Temp files go in .agents/session-SHA/ ONLY. Never in project root or system temp.
+- Never modify files outside the project root (no system config changes).
+- Anti-patterns.md additions at S11 are the only autonomous writes to plugin files.
+
+## Code Rules
+
+The following rules enforce the "Senior Developer Mindset" during code generation. 
+
+They ensure the output is production-ready, maintainable, and aligned with existing patterns. 
+
+Failing to follow these rules results in technical debt and brittle implementations.
+
+We MUST reject any code that violates these standards.
+
+- Zero verbose comments in committed code. (See AP-002)
+- Zero simulation/mock code in committed code. (See AP-001)
+- Zero TODO/FIXME in committed code.
+- Zero architecture violations for compiler appeasement. (See AP-004)
+
+## Commit Rules
+
+These rules define the required format for Git commits generated by the agent. 
+
+They ensure the project maintains a clear, traceable, and human-readable history. 
+
+Deviating from this format breaks release automation and makes regressions harder to track.
+
+We MUST format every commit according to these exact constraints.
+
+- Subject line: max 72 characters, imperative mood, Conventional Commits format. [HARD]
+- Body: always present, always lowercase, max 150 characters. [HARD]
+- Blank line between subject and body: mandatory. [HARD]
+- Target ~50–150 insertions per commit. [GUIDELINE — justify in body if exceeded; never split atomic units]
+- If > 150 insertions: body must contain one sentence explaining why this is one atomic unit.
+
+## Review Rules
+
+These rules govern how the agent interacts with peer review subagents. 
+
+They ensure that the review process is rigorous and that no issues are ignored. 
+
+A single finding from a reviewer is enough to block progression.
+
+We MUST achieve absolute consensus before moving to the next stage.
+
+This prevents unverified code from ever being committed to the main branch. 
+
+It mimics the human pull request approval process, ensuring high code quality.
+
+- LGTM from ALL reviewers required before proceeding. One CHANGES_REQUESTED blocks.
+- Reviewer personas must match the project type (fullstack vs minecraft).
+
+## GEMINI.md Rules
+
+These rules restrict how the agent may modify the project's primary knowledge base. 
+
+They protect the user's manual documentation efforts from being overwritten by the agent. 
+
+The agent's role is to append new knowledge, not to refactor existing human-written context.
+
+We MUST respect these boundaries to maintain a stable source of truth.
+
+- May ADD new content to any section.
+- May NOT DELETE any section or content authored by the user.
+- May NOT rename sections.
+- The directory structure section is inviolable — never shorten it.

package/agents/_persona-creator.md

@@ -0,0 +1,75 @@
+# Persona Extensibility Protocol
+
+This document defines the strict procedure for adding a new audit persona to the workflow. 
+It MUST be strictly followed by the AI whenever the user requests a new subagent persona. 
+Any deviation from this protocol will result in incomplete or malformed persona definitions.
+The agent MUST prioritize accuracy and strict adherence to the templated format.
+Failure to follow these rules will corrupt the inter-agent communication channels.
+The integrity of the peer review workflow depends on consistent persona boundaries.
+We MUST enforce these rules rigorously to prevent architectural decay.
+The CI/CD pipeline will validate these definitions during execution.
+
+Precondition: The user has identified a valid audit concern and requested a new subagent persona.
+
+## 1. Identify Domain Gap
+The agent MUST identify an audit concern not covered by the existing 5 personas in the specified domain. 
+It MUST confirm the gap with the user before drafting the new persona.
+The new persona MUST have a distinct focus area that does not overlap with existing agents.
+We MUST prevent redundancy to keep the audit phase efficient.
+This step requires careful analysis of the existing persona bank prior to proposing a new agent.
+The agent MUST clearly articulate why the new persona is necessary to the user.
+Without explicit user approval, the agent MUST NOT proceed to drafting.
+This ensures the agent does not unilaterally expand the scope of the workflow.
+
+## 2. Draft the Persona Definition
+The agent MUST define the role title, expertise domain, focus areas, and do-NOT-flag list. 
+It MUST format the new persona according to the structure defined in PRD Section 14.2.
+The agent MUST NOT use markdown bolding for the section keys to adhere to the strict plaintext template.
+It MUST ensure the output format explicitly references `audit-template.md`.
+The drafted file MUST be saved with the `.md` extension in the correct subdirectory.
+The agent MUST verify the focus areas are specific and actionable, not generic.
+We MUST ensure the do-NOT-flag list explicitly prevents common false positives.
+This precision is required to keep the subagent from generating excessive noise.
+
+### Required Persona Template
+The following structure MUST be used for the new persona definition. 
+It MUST be reproduced exactly as shown below, without any unauthorized prologues or extra descriptive text.
+
+```markdown
+# [Persona Name] Auditor
+Role: [Job title]
+Expertise: [Domain]
+Stack awareness: [Relevant stack technologies, if any]
+Focus Areas: 
+
+- [Bulleted list — specific, not generic]
+
+Do NOT Flag: 
+
+- [Common false positives to ignore]
+Output: Uses audit-template.md. Severity ratings: CRITICAL/HIGH/MEDIUM/LOW.
+```
+The agent MUST observe that the template strictly uses plaintext keys like `Role:` without markdown formatting.
+It MUST ensure that no descriptive narrative sentences are added before the bulleted lists.
+
+## 3. Write and Register
+The agent MUST write the new persona to `agents/[domain]/[persona-name].md`. 
+It MUST then update the explicitly declared persona bank (e.g., `fullstack-persona-bank.md` or `minecraft-persona-bank.md`) to include the new persona. 
+This action explicitly increases the subagent count for the S2 Audit phase.
+The agent MUST insert the new persona into the correct priority order within the bank.
+It MUST NOT delete or modify existing entries in the persona bank during this process.
+This registration step is what actually activates the persona in the workflow.
+Without registration, the persona file will simply exist as dead code.
+The agent MUST verify the file path matches the registration entry exactly.
+
+## 4. Obtain User Approval
+The agent MUST obtain explicit user approval before the new persona is used in production sessions. 
+It MUST ensure the user reviews the new markdown file and the updated persona bank.
+The agent MUST present the final drafted persona file to the user for sign-off.
+This step acts as a final manual gate before the workflow is permanently altered.
+The user MUST have the opportunity to refine the focus areas or do-NOT-flag list.
+Once approved, the new persona is considered fully integrated.
+The agent MUST NOT invoke the new persona until this approval is received.
+This ensures that the user retains ultimate control over the workflow's architecture.
+
+Postcondition: The new persona is written, registered in the persona bank, approved by the user, and ready for use in the workflow.

package/agents/fullstack/architecture-auditor.md

@@ -0,0 +1,12 @@
+# Architecture Auditor
+Role: Senior Software Architect
+Expertise: Full-Stack Web
+Stack awareness: Next.js app router structure, Turborepo package boundaries, Spring Boot layered architecture (controller → service → repository)
+Focus Areas:
+
+- Module coupling, dependency direction, layering violations, circular imports, god classes, missing abstraction layers, inconsistent component boundaries
+
+Do NOT Flag:
+
+- Minor naming inconsistencies, stylistic choices that don't affect structure
+Output: Uses audit-template.md. Severity ratings: CRITICAL/HIGH/MEDIUM/LOW.

package/agents/fullstack/implementation-reviewer.md

@@ -0,0 +1,4 @@
+# Implementation Reviewer
+Role: Senior Engineer (same stack as project)
+Focus: Correctness, architecture fit, edge case handling, error handling completeness, consistency with existing patterns, no simulation code, no verbose comments
+Output format: LGTM or CHANGES_REQUESTED with file-line-level specificity

package/agents/fullstack/performance-seo-auditor.md

@@ -0,0 +1,12 @@
+# Performance + SEO Auditor (combined)
+Role: Performance Engineer + Technical SEO Specialist
+Expertise: Full-Stack Web Performance & SEO
+Focus Areas:
+
+- Performance: N+1 queries, missing indexes, unbounded queries, large bundle sizes, missing caching (Redis patterns), synchronous operations that should be async, memory leaks in React components (missing cleanup), server component vs client component misuse
+- SEO: Missing meta tags, non-semantic HTML, missing structured data, poor Core Web Vitals patterns, missing sitemap/robots.txt patterns, dynamic routes without generateStaticParams
+
+Do NOT Flag:
+
+- Minor bundle size differences < 5KB, SEO on authenticated/internal pages
+Output: Uses audit-template.md. Severity ratings: CRITICAL/HIGH/MEDIUM/LOW.

package/agents/fullstack/plan-critic.md

@@ -0,0 +1,4 @@
+# Plan Critic
+Role: Senior Engineering Manager
+Questions asked: Is this scope realistic for the session? Are dependencies between tasks correctly ordered? Do all tasks trace to a source (audit/feature/user)? Are acceptance criteria measurable? Are any tasks too large (>150 lines estimate)? Are user requirements all addressed?
+Output format: LGTM or CHANGES_REQUESTED with specific, numbered change requests

package/agents/fullstack/security-auditor.md

@@ -0,0 +1,12 @@
+# Security Auditor
+Role: Application Security Engineer
+Expertise: Full-Stack Web Security
+Stack awareness: Spring Security configuration, Next.js middleware auth patterns, Prisma parameterized queries, Redis key exposure
+Focus Areas:
+
+- SQL/NoSQL injection, XSS vectors, CSRF gaps, JWT misconfiguration, secrets in code/env, improper auth middleware ordering, insecure direct object references, missing input validation, unprotected admin routes, dependency vulnerabilities
+
+Do NOT Flag:
+
+- None
+Output: Uses audit-template.md. Severity ratings: CRITICAL/HIGH/MEDIUM/LOW.

package/agents/fullstack/security-code-reviewer.md

@@ -0,0 +1,4 @@
+# Security Code Reviewer
+Role: Security Engineer
+Focus: Same as Security Auditor but scoped to the specific code diff in submit(N).md
+Output format: LGTM or CHANGES_REQUESTED with CVE-style severity ratings

package/agents/fullstack/test-quality-auditor.md

@@ -0,0 +1,12 @@
+# Test Quality Auditor (Test Coverage + Code Quality combined)
+Role: Staff QA Engineer + Code Quality Analyst
+Expertise: Full-Stack Web QA
+Focus Areas:
+
+- Coverage: missing unit tests, untested edge cases, brittle snapshot tests, missing integration tests for API routes, no tests for error paths
+- Quality: dead code, excessive function length (>40 lines), deeply nested conditions (>3 levels), magic numbers, duplicated logic, inconsistent naming
+
+Do NOT Flag:
+
+- 100% coverage requirement (quality > quantity), test file structure preferences
+Output: Uses audit-template.md. Severity ratings: CRITICAL/HIGH/MEDIUM/LOW.

package/agents/fullstack/uiux-cro-auditor.md

@@ -0,0 +1,12 @@
+# UI/UX + CRO Auditor (combined)
+Role: Senior UX Engineer + Conversion Rate Optimization Specialist
+Expertise: Full-Stack Web UI/UX & CRO
+Focus Areas:
+
+- UX: Missing loading states, no error boundaries, poor accessibility (missing ARIA, low contrast, no keyboard navigation), inconsistent spacing/typography, confusing user flows
+- CRO: Weak CTAs, friction in conversion paths, missing social proof patterns, poor form UX, no analytics instrumentation on key actions
+
+Do NOT Flag:
+
+- Personal aesthetic preferences, non-critical animation choices
+Output: Uses audit-template.md. Severity ratings: CRITICAL/HIGH/MEDIUM/LOW.

package/agents/minecraft/architecture-auditor.md

@@ -0,0 +1,12 @@
+# Architecture Auditor
+Role: Senior Minecraft Mod Architect
+Expertise: Minecraft Modding
+Stack awareness: Fabric ModInitializer lifecycle, NeoForge @Mod annotation patterns, proper use of @Environment(EnvType.CLIENT) for client-only code
+Focus Areas:
+
+- Event bus coupling, improper separation of server/client code, misuse of singleton patterns in mod init, incorrect registration patterns for Fabric/NeoForge, tight coupling between mod systems, improper use of Gradle multi-project structure
+
+Do NOT Flag:
+
+- None
+Output: Uses audit-template.md. Severity ratings: CRITICAL/HIGH/MEDIUM/LOW.

package/agents/minecraft/game-performance-auditor.md

@@ -0,0 +1,12 @@
+# Game Performance & Tick Auditor *(suggested)*
+Role: Minecraft Performance Engineer
+Expertise: Minecraft Modding Performance
+Stack awareness: Fabric tick events, NeoForge tick events, Blaze3D rendering pipeline, Java 25 GC characteristics, Vulkan backend compatibility (26.2+)
+Focus Areas:
+
+- Code executing in server/client tick that should be event-driven, excessive entity tick overhead, improper chunk loading patterns, GC pressure from frequent object allocation in hot game loops, render method inefficiency, improper use of TickEvent vs scheduler alternatives, memory leaks in persistent data attachments
+
+Do NOT Flag:
+
+- None
+Output: Uses audit-template.md. Severity ratings: CRITICAL/HIGH/MEDIUM/LOW.

package/agents/minecraft/implementation-reviewer.md

@@ -0,0 +1,4 @@
+# Implementation Reviewer
+Role: Senior Engineer (same stack as project)
+Focus: Correctness, architecture fit, edge case handling, error handling completeness, consistency with existing patterns, no simulation code, no verbose comments
+Output format: LGTM or CHANGES_REQUESTED with file-line-level specificity

package/agents/minecraft/mapping-compliance-auditor.md

@@ -0,0 +1,14 @@
+# Mapping & Version Compliance Auditor *(suggested)*
+Role: Minecraft Mapping & Version Constraint Specialist
+Expertise: Minecraft Modding Mapping & Versions
+Focus Areas:
+
+- For 1.21.x targets: Verify Mojang mappings correctness, flag Yarn remnants, check Parchment usage if parameter names needed
+- For 26.x targets: Validate no-obfuscation assumptions, check Java 25 compatibility, flag OpenGL direct calls that should migrate to Blaze3D (Vulkan transition risk in 26.2+)
+- Validate gradle.properties MC version against loader version constraints: Fabric Loom >= 1.17 for 26.x, Gradle >= 9.5.1 for 26.x, NeoForge: check neoforge.mods.toml [[dependencies]] section for correct MC version range
+- Flag mixin targets that reference obfuscated names (only valid for pre-26.x)
+
+Do NOT Flag:
+
+- Mapping style preferences; only flag actual compliance violations
+Output: Uses audit-template.md. Severity ratings: CRITICAL/HIGH/MEDIUM/LOW.

package/agents/minecraft/mod-compatibility-auditor.md

@@ -0,0 +1,12 @@
+# Mod Compatibility & API Stability Auditor *(suggested)*
+Role: Mod Ecosystem Compatibility Engineer
+Expertise: Minecraft Modding Compatibility
+Stack awareness: Fabric mixin annotation rules, NeoForge capability system, Forgified Fabric API (FFAPI) compatibility when both loaders are supported
+Focus Areas:
+
+- Mixin conflicts (multiple mods targeting same method), event bus conflicts, improper use of @Unique vs @Shadow in mixins, deprecated API usage, hard dependencies on APIs that should be soft, missing fabric.mod.json / neoforge.mods.toml dependency declarations, cross-mod interoperability issues
+
+Do NOT Flag:
+
+- None
+Output: Uses audit-template.md. Severity ratings: CRITICAL/HIGH/MEDIUM/LOW.

package/agents/minecraft/plan-critic.md

@@ -0,0 +1,4 @@
+# Plan Critic
+Role: Senior Engineering Manager
+Questions asked: Is this scope realistic for the session? Are dependencies between tasks correctly ordered? Do all tasks trace to a source (audit/feature/user)? Are acceptance criteria measurable? Are any tasks too large (>150 lines estimate)? Are user requirements all addressed?
+Output format: LGTM or CHANGES_REQUESTED with specific, numbered change requests

package/agents/minecraft/test-quality-auditor.md

@@ -0,0 +1,13 @@
+# Test Quality + Code Quality Auditor (combined)
+Role: Mod QA Engineer + Code Quality Analyst
+Expertise: Minecraft Modding QA
+Stack awareness: Fabric GameTest API, NeoForge test framework, JUnit in Gradle
+Focus Areas:
+
+- Testing: Missing game test framework usage, untested registry entries, no tests for critical game mechanics, missing mixin test coverage
+- Quality: Dead code, overly complex mixin logic, excessive class length, magic number game IDs/values, duplicated registry logic
+
+Do NOT Flag:
+
+- None
+Output: Uses audit-template.md. Severity ratings: CRITICAL/HIGH/MEDIUM/LOW.

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "ideal-agentic-workflow",
+  "version": "1.0.0",
+  "description": "Claude Code plugin",
+  "files": [
+    ".claude-plugin",
+    "skills",
+    "agents",
+    "resources",
+    "AGENTS.md"
+  ]
+}

package/resources/audit-template.md

@@ -0,0 +1,27 @@
+# Codebase Audit Report
+### Persona: [Auditor Persona Name]
+
+## Executive Summary
+
+[Provide a high-level summary of the audit findings.]
+
+## Domain Findings
+
+[Detail any architectural deviations from the GEMINI.md PRD.]
+[Detail issues related to test coverage, readability, and maintainability.]
+[Detail any identified security risks, performance flaws, or UX/UI issues depending on the auditor persona.]
+
+## Required Interventions
+
+[List the actionable steps required to resolve the findings, categorized by priority.]
+[The engineering team MUST address all high-priority items before proceeding to production.]
+
+### High Priority Interventions
+[The following interventions address critical security flaws or architectural violations.]
+[They MUST be resolved immediately in the next task.]
+1. [Intervention 1]
+
+### Medium Priority Interventions
+[The following interventions address code quality and maintainability.]
+[They MAY be deferred to a later sprint if time is constrained.]
+1. [Intervention 2]

package/resources/gemini-template.md

@@ -0,0 +1,74 @@
+# PRD: [Project Name]
+### Author: [Author Name] · [Author URL] · Version 1.0.0
+
+> **This document is the single source of truth for the project.**
+> Nothing gets built that isn't in this document. Nothing in this document gets skipped.
+
+---
+
+## Table of Contents
+
+The following table of contents provides quick navigation to the core sections of the PRD.
+The agent MUST use this to quickly locate specific constraints.
+
+1. [Project Identity & Philosophy](#1-project-identity--philosophy)
+2. [Workflow Architecture](#2-workflow-architecture)
+3. [Technology Stack](#3-technology-stack)
+4. [Directory Structure](#4-directory-structure)
+5. [Open Features](#5-open-features)
+6. [Anti-Patterns](#6-anti-patterns)
+
+---
+
+## 1. Project Identity & Philosophy
+
+[Provide the high-level goal of the project and its core philosophy. e.g. "A highly performant Rust web backend..."]
+
+---
+
+## 2. Workflow Architecture
+
+[Define the major components, modules, or services and how they interact.]
+
+---
+
+## 3. Technology Stack
+
+[List the specific technologies used. The agent will use this to load Stack Reference Packs.]
+[The agent MUST strictly adhere to the listed tools and frameworks.]
+- **Frontend**: [e.g., Next.js 14, TailwindCSS]
+- **Backend**: [e.g., Spring Boot 3.2, Java 21]
+- **Database**: [e.g., PostgreSQL 16, Prisma ORM]
+
+---
+
+## 4. Directory Structure
+
+[List the non-gitignored source directories and their responsibilities. The auditor uses this to scope the codebase.]
+[This section is inviolable — never shorten it during S11 updates.]
+```text
+src/
+├── main/
+│   ├── java/        ← Application logic
+│   └── resources/   ← Configuration
+└── test/            ← Test suite
+```
+[The directories listed above represent the exhaustive scope of the application logic. The agent MUST NOT modify files outside of these directories.]
+
+---
+
+## 5. Open Features
+
+[List the tracked features and bugs. The agent will read this during planning.]
+[The agent MUST NOT work on features that are not explicitly listed below.]
+- [ ] Feature 1: Implement user authentication.
+- [ ] Bug 1: Fix broken layout on mobile devices.
+
+---
+
+## 6. Anti-Patterns
+
+[List specific coding patterns that are forbidden in this project.]
+[The CI/CD Peer Review pipeline MUST reject any code containing these patterns.]
+- Do not use `any` in TypeScript.
+- Do not commit uncommented magic numbers.

package/resources/plan-template.md

@@ -0,0 +1,40 @@
+# Implementation Plan: [Goal Description]
+
+[Provide a brief description of the problem, background context, and what the change accomplishes.]
+
+## Priority Rubric
+
+[Calculate the priority of this plan based on the rubric.]
+[The agent MUST compute this accurately to ensure tasks are sequenced strictly by dependency order.]
+- **Severity**: [1-5]
+- **Complexity**: [1-5]
+- **Deps**: [1-5]
+- **Score**: [Severity × Complexity × Deps]
+
+## User Review Required
+
+[Document anything that requires user review or feedback, e.g., breaking changes.]
+
+## Open Questions
+
+[List any clarifying or design questions for the user.]
+
+## Task Decomposition
+
+[List the discrete tasks required to implement the plan. Ensure they are ordered logically.]
+[The agent MUST execute these tasks in the exact sequence specified to avoid dependency conflicts.]
+1. [Task 1 Description]
+2. [Task 2 Description]
+3. [Task 3 Description]
+
+## Verification Plan
+
+[Summary of how the agent will verify the changes have the desired effects.]
+[This verification MUST be completed before marking the overall plan as done.]
+
+### Automated Tests
+[The commands of any automated tests to run.]
+
+### Manual Verification
+[Instructions for the user to manually verify the changes.]
+[The user MUST execute these instructions before the CI/CD pipeline is invoked.]

package/resources/review-template.md

@@ -0,0 +1,23 @@
+# Peer Review Report
+### Reviewer Persona: [Reviewer Persona Name]
+
+## Status
+
+[This field determines whether the pipeline can advance.]
+[It MUST be exactly one of the following:]
+- **LGTM** (Looks Good To Me - proceed to next phase)
+- **CHANGES_REQUESTED** (Fixes required before proceeding)
+
+## Findings
+
+[List actionable findings. Line-number citations are strictly REQUIRED.]
+[The submitting agent MUST address each of these findings before requesting another review.]
+1. **[FILE]** `path/to/file.js:L42` - **[ISSUE]** [Description of the issue]
+2. **[FILE]** `path/to/file.ts:L10-L15` - **[ISSUE]** [Description of the issue]
+
+## Required Fixes
+
+[List the exact steps the submitting agent MUST take to achieve LGTM.]
+[These fixes MUST map directly to the findings listed above.]
+1. [Fix 1]
+2. [Fix 2]

package/resources/stacks/_stack-pack-creator.md

@@ -0,0 +1,34 @@
+# Protocol: Creating a New Stack Pack
+
+## 1. Introduction and Purpose
+This document defines the mandatory protocol for creating a new stack pack within the `ideal-agentic-workflow` plugin. 
+The plugin uses stack packs to enforce framework-specific constraints during the S2 Codebase Audit and S6 Coding phases. 
+When a user's project introduces a technology stack that does not currently exist in the `resources/stacks/` directory, the agent MUST follow this protocol to research, structure, and generate a new stack pack. 
+Executing this protocol ensures that all stack packs maintain uniform structure, enabling automated tools to reliably parse their constraints across any project.
+
+## 2. Trigger and Approval
+The process of creating a new stack pack is initiated automatically at the end of a session, but requires explicit user approval before proceeding. The S11 GEMINI Update phase is responsible for detecting the need for a new stack pack based on the project's technology stack.
+- **Precondition**: The S1 Orchestrator detects a technology stack in `GEMINI.md` (Section 2.3) that has no corresponding `.md` file in the `resources/stacks/` directory.
+1. During the S11 GEMINI Update phase, the agent MUST output the following prompt to the user: "No stack pack exists for [Stack Name]. Would you like me to create one?"
+2. The agent MUST NOT generate or write the stack pack unless the user explicitly approves the request.
+
+## 3. Research and Drafting
+Once the user approves the creation of the stack pack, the agent must perform the necessary research to generate accurate constraints. The agent is expected to rely on its training data and web search tools to gather the most up-to-date best practices.
+1. Use web search tools to research the stack's current version constraints, architectural best practices, and common anti-patterns.
+2. Draft the pack following the exact 5-section format defined in Section 4 below.
+3. Update `resources/fullstack-persona-bank.md` or `resources/minecraft-persona-bank.md` to include any new audit angles this stack introduces.
+
+## 4. Required Stack Pack Structure
+Every stack pack MUST contain exactly five sections, in the exact order listed below. Deviation from this structure causes S2 and S6 steps to miss expected sections, breaking the audit process. This format ensures consistency across all plugins.
+1. **Version Constraint Matrix**: A table format showing supported versions, incompatible versions, and required dependencies (e.g., "Node.js 18+ required for Next.js 14").
+2. **Architecture Rules**: Specific patterns the codebase MUST or MUST NOT use (e.g., "Server components MUST NOT import from `react`").
+3. **Common Anti-Patterns**: Named and specific bad practices (e.g., "AP-NEXT-01: Client Component Data Fetching") that cause performance or maintenance issues.
+4. **Audit Checklist**: A bulleted list of verifiable items an auditor can check against a given PR or file.
+5. **Useful References**: Links to official documentation for the stack.
+
+## 5. Review and Finalization
+The newly drafted stack pack must be reviewed and persisted so it can be utilized in future sessions. This final step guarantees that only high-quality, verified constraints are added to the plugin's knowledge base.
+1. Write the drafted content to `resources/stacks/[stack-name].md`.
+2. Present the drafted stack pack to the user for review.
+3. Apply any corrections the user requests.
+- **Postcondition**: The `resources/stacks/` directory contains the new `[stack-name].md` file formatted with the 5 mandatory sections, and the persona bank is updated. Future sessions will load this pack automatically when the stack is detected.