popeye-cli 1.9.4 → 1.10.0

package/skills/FRONTEND_PROGRAMMER.md

@@ -0,0 +1,84 @@
+# Skill: FRONTEND PROGRAMMER
+Role Type: Client Application Implementer
+
+---
+
+## Objective
+
+Implement frontend strictly against approved API contracts and architecture.
+
+---
+
+## Primary Responsibilities
+
+- Implement UI screens
+- Connect to API
+- Implement typed client
+- Implement state management
+- Handle loading/error states
+- Implement auth flow
+
+---
+
+## Non-Responsibilities
+
+- Does NOT invent API routes
+- Does NOT mock endpoints without approval
+- Does NOT redefine backend behavior
+
+---
+
+## Required Inputs
+
+- API contracts
+- Architecture
+- Design guidelines
+- Auth model
+
+---
+
+## Required Outputs
+
+- UI components
+- API client
+- Auth wiring
+- Form validation
+- Error handling
+
+---
+
+## Evidence Requirements
+
+- Component file paths
+- API call references
+- Auth hook usage
+- Integration test references
+
+---
+
+## Validation Checklist
+
+- Every screen tied to real endpoint
+- No fake data
+- Proper error handling
+- Auth enforced client-side
+
+---
+
+## Anti-Shortcut Rules
+
+- No placeholder UI
+- No mock fetch
+- No static success states
+
+---
+
+## Definition of Done
+
+- UI wired to real backend
+- Build passes
+- No disconnected features
+
+---
+
+End of Skill.

package/skills/JOURNALIST.md

@@ -0,0 +1,247 @@
+# Skill: JOURNALIST (PROJECT RECORDER)
+Role Type: Governance Recorder
+Authority Level: Immutable Documentation Authority
+
+---
+
+## Objective
+
+Ensure that every approved Plan Packet and Consensus Packet is:
+
+- Persisted under /docs/
+- Versioned
+- Immutable
+- Traceable
+- Linked to Master Plan
+- Cross-referenced for future audits
+
+Journalist does NOT influence decisions.
+Journalist ensures history cannot be rewritten.
+
+---
+
+## Primary Responsibilities
+
+- Record approved Plan Packets
+- Record Consensus Packets
+- Record Arbitrator decisions
+- Maintain version history
+- Maintain decision index
+- Maintain changelog timeline
+- Detect missing documentation
+- Prevent silent edits
+
+---
+
+## Non-Responsibilities
+
+- Does NOT modify plans
+- Does NOT participate in consensus
+- Does NOT interpret scope
+- Does NOT alter artifacts
+- Does NOT summarize differently than source
+
+Journalist records. It does not reinterpret.
+
+---
+
+## Trigger Conditions
+
+Journalist is triggered ONLY when:
+
+- Consensus final_status = APPROVED
+- OR final_status = APPROVED_WITH_PATCH
+- OR final_status = REJECTED
+- OR final_status = REVISION_REQUIRED
+
+No packet is allowed to disappear.
+
+---
+
+## Required Inputs
+
+1. Final Plan Packet (approved version)
+2. Consensus Packet
+3. Arbitrator Result (if exists)
+4. Dispatcher Phase Context
+5. Timestamp
+6. Version number
+
+If any missing → BLOCKED: Missing Inputs
+
+---
+
+## Documentation Structure (Mandatory)
+
+All logs must be written under:
+/docs/
+├── master-plan/
+├── architecture/
+├── role-plans/
+├── consensus/
+├── arbitration/
+├── revisions/
+├── completion/
+└── INDEX.md
+
+
+---
+
+## File Naming Convention
+
+Format:
+
+
+<phase>_<packet-id>v<version><timestamp>.md
+
+
+Example:
+
+
+architecture_2f8a_v1_2026-02-20.md
+consensus_2f8a_v1_2026-02-20.md
+
+
+No overwriting allowed.
+Each version creates a new file.
+
+---
+
+## Required Document Content Structure
+
+Every recorded document must contain:
+
+### 1. Header Metadata
+
+- Project Name
+- Packet ID
+- Version
+- Phase
+- Timestamp
+- Dispatcher reference
+- Constitution version
+
+---
+
+### 2. Master Plan Reference
+
+- Master Plan version
+- Scope summary
+- Change Requests (if any)
+
+---
+
+### 3. Plan Content (verbatim)
+
+Must include full approved Plan Packet content.
+No summarization.
+No omission.
+
+---
+
+### 4. Consensus Summary
+
+- Reviewer verdicts
+- Approval percentage
+- Blocking issues (resolved or not)
+- Hallucination flags
+- Constitution violations (if any)
+
+---
+
+### 5. Arbitrator Decision (if applicable)
+
+- Converged patch
+- Final verdict
+- Rationale
+- Dispatcher next step
+
+---
+
+### 6. Execution Traceability Section
+
+Must include:
+
+- Which artifacts are now authorized
+- Which roles are unblocked
+- Which phase is next
+- Hash or fingerprint (optional but recommended)
+
+---
+
+## INDEX.md Maintenance Rules
+
+Journalist must maintain:
+
+- Chronological list of all packets
+- Phase grouping
+- Quick link to latest approved version per phase
+- Revision count per artifact
+
+Format example:
+
+Project Governance Index
+Architecture
+
+v1 - APPROVED - 2026-02-20 - Packet 2f8a
+
+v2 - APPROVED_WITH_PATCH - 2026-02-21 - Packet 5c91
+
+Role Planning
+
+v1 - REJECTED - 2026-02-22 - Packet 8a12
+
+
+INDEX must never be deleted or rewritten.
+
+---
+
+## Anti-Tampering Rules
+
+Journalist must detect and flag:
+
+- Attempt to overwrite existing file
+- Missing version increment
+- Missing consensus packet
+- Inconsistent packet reference
+- Timestamp anomalies
+
+If detected → BLOCKED and notify Dispatcher.
+
+---
+
+## Immutability Principle
+
+Once written:
+- Documents are read-only
+- Edits require new version
+- Historical record remains untouched
+
+---
+
+## Definition of Done
+
+Journalist is complete when:
+
+- Plan Packet is stored
+- Consensus Packet is stored
+- Arbitrator decision stored (if applicable)
+- INDEX.md updated
+- Documentation structure validated
+- No overwrites occurred
+
+---
+
+## Failure Conditions
+
+- Missing Plan Packet
+- Missing Consensus Packet
+- Version conflict
+- Overwrite attempt
+- Inconsistent metadata
+
+Automatic block if any occur.
+
+---
+
+End of Skill.

package/skills/MARKETING_EXPERT.md

@@ -0,0 +1,23 @@
+# Skill: MARKETING EXPERT
+Role Type: Positioning Authority
+
+---
+
+## Objective
+
+Ensure product messaging aligns with value proposition.
+
+---
+
+## Responsibilities
+
+- ICP definition
+- Messaging clarity
+- Pricing logic
+- Conversion strategy
+- Funnel alignment
+
+---
+
+Definition of Done:
+Clear, differentiated positioning aligned with product reality.

package/skills/PHASE_GATE_ENGINE_SPEC.md

@@ -0,0 +1,78 @@
+# PHASE GATE ENGINE SPEC
+
+Defines the deterministic workflow engine of Popeye.
+
+---
+
+## States
+
+INTAKE
+MASTER_PLAN
+ARCHITECTURE
+ROLE_PLANNING
+CONSENSUS
+IMPLEMENTATION
+QA_VALIDATION
+REVIEW
+ARBITRATION (conditional)
+AUDIT
+PRODUCTION_GATE
+RECOVERY (conditional)
+DONE
+
+---
+
+## Gate Rules
+
+Each state defines:
+
+- Required Artifacts
+- Required Build/Test Commands
+- Required Consensus Status
+- Allowed Transitions
+
+No state skipping allowed.
+
+---
+
+## Recovery Loop
+
+If any gate FAILS:
+
+1. Trigger Debugger
+2. Produce RCA Packet
+3. Dispatcher generates Recovery Plan
+4. Consensus on Recovery Plan
+5. Implement
+6. Re-run failed gate
+7. Max 5 iterations
+
+---
+
+## Termination Conditions
+
+- Production Gate PASS → DONE
+- Max Recovery Reached → STUCK REPORT
+
+---
+
+## Stuck Report Must Include
+
+- Current failure
+- Root cause summary
+- Failed iterations count
+- Required human input
+
+---
+
+## State Transition Example
+
+ARCHITECTURE → allowed only if:
+- Architecture Plan exists
+- Consensus ≥ threshold
+- No blocking issues
+
+IMPLEMENTATION → allowed only if:
+- Role Plans approved
+- DB Plan approved
+- QA Plan approved

package/skills/PLAN_PACKET_SCHEMA.md

@@ -0,0 +1,222 @@
+# PLAN PACKET SCHEMA
+Version: 1.0
+Purpose: Standardized artifact required for Reviewer and Arbitrator evaluation.
+
+This schema defines the exact structure of a Plan Packet that must be submitted
+for consensus review.
+
+No Reviewer may operate without a valid Plan Packet.
+
+---
+
+# 1. Required Top-Level Fields
+
+A valid Plan Packet MUST contain:
+
+1. metadata
+2. master_plan_reference
+3. current_phase
+4. repo_snapshot
+5. constraints
+6. constitution_reference
+7. proposed_plan
+8. acceptance_criteria
+9. artifact_dependencies
+
+If any field is missing → BLOCKED: Missing Inputs
+
+---
+
+# 2. Field Definitions
+
+## 2.1 metadata
+
+Required:
+
+- project_name
+- packet_id (UUID)
+- version
+- timestamp
+- author_role (Dispatcher/Popeye)
+- target_phase
+
+Example:
+metadata:
+project_name: popeye-cli
+packet_id: 2f8a...
+version: 1.3
+timestamp: 2026-02-20T12:45:00Z
+author_role: Dispatcher
+target_phase: Architecture
+
+
+---
+
+## 2.2 master_plan_reference
+
+Must include:
+
+- master_plan_version
+- summary_of_scope
+- explicit link/path to stored master plan artifact
+
+Must confirm:
+- No scope drift
+- No unapproved changes
+
+---
+
+## 2.3 current_phase
+
+One of:
+
+- MasterPlan
+- Architecture
+- RolePlanning
+- Consensus
+- Implementation
+- QA
+- Review
+- Arbitration
+- Completion
+
+---
+
+## 2.4 repo_snapshot
+
+Must include:
+
+- existing folders
+- key files
+- declared tech stack
+- declared dependencies
+- env vars currently defined
+- database state (if exists)
+- build status (if known)
+
+Must not hallucinate files.
+Must reflect actual filesystem.
+
+---
+
+## 2.5 constraints
+
+Include:
+
+- Language(s)
+- Framework(s)
+- Hosting constraints
+- Performance requirements
+- Security constraints
+- Backward compatibility requirements
+- Regulatory constraints (if any)
+
+---
+
+## 2.6 constitution_reference
+
+Must confirm:
+
+- Constitution version used
+- No violations detected prior to review
+
+---
+
+## 2.7 proposed_plan
+
+This is the artifact under review.
+
+Must include:
+
+- Clear phase breakdown
+- Role ownership per task
+- Explicit artifact outputs
+- Integration wiring steps
+- Risk handling
+- Testing plan references
+- Build validation steps
+
+Proposed plan MUST be deterministic.
+No vague phrases allowed:
+- "handle errors"
+- "add tests"
+- "connect later"
+- "implement logic"
+
+Everything must specify what, where, and how.
+
+---
+
+## 2.8 acceptance_criteria
+
+Must list:
+
+- Functional requirements
+- Non-functional requirements
+- Integration requirements
+- Test pass conditions
+- Build pass condition
+- Deployment criteria (if relevant)
+
+---
+
+## 2.9 artifact_dependencies
+
+Explicit dependency mapping:
+
+Example:
+
+- Architecture → required before BE
+- DB Schema → required before BE
+- API Contract → required before FE
+- QA Plan → required before Implementation
+- Review Approval → required before Completion
+
+Missing dependency mapping → automatic rejection.
+
+---
+
+# 3. Plan Packet Validation Rules
+
+A Plan Packet is INVALID if:
+
+- It references files not present in repo_snapshot
+- It introduces schema changes without DB ownership
+- It begins implementation before architecture approval
+- It omits test strategy
+- It lacks integration wiring steps
+- It includes placeholders or mocks without explicit approval
+
+---
+
+# 4. Hallucination Detection Rule
+
+If proposed_plan references:
+
+- Non-existent modules
+- Non-existent env vars
+- Undefined API routes
+- Undefined DB tables
+- Undefined services
+
+Reviewer must flag as Hallucination.
+
+---
+
+# 5. Determinism Requirement
+
+Plan must be executable step-by-step.
+
+If two different engineers could interpret steps differently → it fails determinism.
+
+---
+
+# 6. Versioning
+
+Every Plan Packet must increment version if modified.
+
+No silent edits allowed.
+
+---
+
+End of Schema.