PlanBot is a specialized resource for agentic planning and architectural design. It operates as an autonomous sub-agent to generate comprehensive implementation plans, security constraints, and strategy documents.
This package contains:
- agent/workspace/: A snapshot of the PlanBot agent's workspace, containing its configuration, memory, and generated plans.
The PlanBot architecture is designed as a Stateful Multi-Agent Orchestration Loop. Unlike standard linear pipelines, this system emphasizes traceability through an append-only reasoning log and resilience via a high-level circuit breaker (REPLAN). The design transitions from "stateless generation" to "stateful engineering," ensuring that every architectural decision is grounded in security constraints and strategic intent.
The system operates in a five-phase cycle. Each phase produces a permanent artifact and appends to a shared reasoning log.
graph TD
User([User Request]) --> P1[Phase 1: Planner]
P1 --> S[01_strategy.md]
S --> P2[Phase 2: Security Counsel]
P2 --> SC[02_security_constraints.md]
SC --> P3[Phase 3: Architect]
P3 --> ARCH[03_architecture.md]
ARCH --> P4[Phase 4: Implementation Engineer]
P4 --> SPEC[04_implementation_specs.md]
SPEC --> P5[Phase 5: Auditor]
P5 --> AUDIT[05_final_audit.md]
AUDIT -- VERDICT: FAIL --> P3
AUDIT -- VERDICT: REPLAN --> P1
AUDIT -- VERDICT: PASS --> End([Finalized Plan])
- Role: Manages the lifecycle of the planning session.
- Responsibility:
- Enforces the Convergence Limit (max 3 loops).
- Triggers the
REPLANcircuit breaker when the Auditor detects fundamental flaws. - Pins Persona IDs to output blocks to prevent spoofing.
- Role: Centralized state for agent "thoughts."
- Responsibility: Captures the why behind each artifact. It is append-only to maintain an immutable audit trail of the decision-making process.
- Planner (01): Defines high-level strategy and research requirements.
- Security Counsel (02): Performs STRIDE threat modeling and sets hard constraints.
- Architect (03): (Current) Translates strategy and constraints into a technical system design.
- Implementation Engineer (04): Converts architecture into actionable, least-privilege technical specs.
- Auditor (05): Validates the entire package against security "Red Lines" and strategic alignment.
- Context: Previous iterations lost context during loop resets.
- Decision: All agents must write their internal reasoning to
plan/reasoning.logbefore generating their final artifact. - Consequence: Provides the Architect and Auditor with the full history of why a previous attempt failed, preventing repetitive errors.
- Context: Downstream agents (e.g., Implementation) were modifying upstream goals (Strategy).
- Decision: Once an artifact is produced and the phase is passed, it is read-only for subsequent agents. Only a
REPLANverdict from the Auditor can unlock an upstream file for modification. - Consequence: Ensures architectural integrity and prevents "scope creep" during implementation.
- Context: Security was often an afterthought or a generic checklist.
- Decision: The Architecture must explicitly map components to the risks identified in
02_security_constraints.md. - Consequence: Security is "baked in" to the data flow rather than added as a wrapper.
| Constraint (from 02_security_constraints.md) | Design Implementation |
|---|---|
| SC-1: Integrity of Reasoning Chain | Append-only reasoning.log with mandatory Persona ID tagging ([Persona-XX]). |
| SC-2: Input/Research Sanitization | The Planner (Phase 1) acts as a sanitization gateway; no raw external data is passed directly to the Architect. |
| SC-3: Least Privilege Specs | The Implementation Specs (Phase 4) are required to include a "Permissions Required" manifest for every proposed action. |
| SC-4: Artifact Sanitization | Use of <PROJECT_ROOT> placeholders and relative paths is standardized in the Architecture template. |
- No Shell Injection: Architecture mandates parameterized execution blocks for all proposed scripts.
- No Network Egress: The system design for PlanBot is air-gapped from external networks during the Architecture/Implementation phases unless a specific "Research Requirement" is flagged by the Planner.
- No Auto-Execution: The orchestrator is designed to output files, never to execute the generated
04_implementation_specs.md.
- Conflict: The need for "Stateful Reasoning" (ADR-001) increases the context window size, potentially leading to "Context Drift" or token exhaustion.
- Mitigation: The Orchestrator will implement Reasoning Summarization if the log exceeds a specific threshold, ensuring only the most recent "Lessons Learned" and the original "Core Intent" are preserved in high fidelity.
- Conflict: Strict "Artifact Immutability" (ADR-002) may slow down development if small strategy tweaks are needed.
- Mitigation: The
REPLANcircuit breaker allows for targeted strategy updates, but it increments the loop counter, enforcing the Convergence Limit to prevent infinite loops.
Architecture Design Completed by Phase 3: Distinguished Architect.