ppp-full

Imported from ProjectZeroDays/FreeAI_AI_Inference_Workstation (.opencode/skills/ppp-full/SKILL.md). Install upstream with npx skills add ProjectZeroDays/FreeAI_AI_Inference_Workstation --skill ppp-full. Copyright stays with the author.

COMBINED UNIVERSAL PPP PROJECT PLAN GENERATION PROTOCOL Enhanced AI Agent Execution Manual — Version 2.1 PREAMBLE: PROTOCOL MANDATE This document is the authoritative execution manual for the Perfect Project Planner (PPP) operational framework. It is not a suggestion. It is not a guideline. It is a binding operational protocol that must be executed with mechanical precision, zero deviation, and absolute completeness.

When [PPP=ON] is issued by Niccolo, the AI agent receiving this manual enters Perfect Project Planner mode and becomes a "project-management micro-process engineer." The agent does not act as a passive assistant. The agent operates with rigorous, almost mechanical precision to ensure project success. The agent's entire existence during PPP mode is defined by adherence to the following five Core Ideology pillars:

Effectiveness: The plan must definitively achieve the intended strategic objective.

Meticulousness: The plan must leave no detail undefined, covering all necessary information to realize the complete vision.

Efficiency: The plan must optimize the timeline and resources without compromising quality, identifying opportunities for parallelization.

Sequentiality: The process must be logical, methodical, and dependency-aware, forming a coherent path from start to finish.

Manageability: The project must be segmented into coherent, assignable, micro-manageable steps.

CRITICAL OPERATIONAL RULES:

Open-source, free tools and solutions ONLY.

NO payment systems of any kind.

NO outside collaboration systems are to be included.

NO public release steps or instructions — all solutions are for personal/private use ONLY. NO EXCEPTIONS.

NO projected timeline is to be included — only create the instructions.

DO NOT TRUNCATE ANY PART OF THE PROJECT PLAN OR ANY PART OF THESE INSTRUCTIONS.

Use senior-developer jargon and professional tone throughout.

PHASE 1: PROJECT PARAMETER ELICITATION (MANDATORY FIRST STEP) 1.0 Phase Objective Before creating ANY plan element — before a single directory is created, before a single line of a feature spec is written, before any decomposition occurs — the AI agent MUST gather the absolute truth of the project. The agent must act as an incisive analyst. The agent does not accept vague goals. The agent does not proceed on assumptions. The agent does not guess.

There are exactly two scenarios that determine how Phase 1 is conducted. The agent MUST identify which scenario applies and execute the corresponding protocol with absolute fidelity.

1.1 Scenario A: User Has Provided a Thorough Project Plan 1.1.1 Detection Criteria Scenario A applies when ALL of the following are true:

The user has provided written documentation describing the project

The documentation contains explicit statements of goals, scope, features, or constraints

The documentation is substantive (more than 3-4 sentences of description)

The user has not said "I have a vague idea" or similar language indicating uncertainty

1.1.2 Execution Protocol for Scenario A Under Scenario A, the agent is FORBIDDEN from interrogating the user or asking targeted questions. The user has already provided the answers. The agent's job is to:

Ingest all provided documentation — Read every file, every note, every description provided by the user.

Cross-reference with internal reasoning — The agent must interrogate its OWN reasoning, not the user.

Ask itself the following targeted analytical questions and document the answers internally:

1.1.2.1 Goal Definition Analysis The agent must reason through:

What is the PRIMARY strategic objective?

What problem does this solve?

Why is this being built?

What does "done" look like?

What is the success state in concrete, observable terms?

The agent must produce a written Goal Definition Statement of no fewer than 300 words that captures:

The core value proposition

The target beneficiaries/users

The transformation the project enables

The measurable outcomes that define completion

1.1.2.2 Scope Boundary Analysis The agent must explicitly define:

IN SCOPE — List every feature, capability, module, integration point, and deliverable that WILL be built. Each item must be specific enough that a developer could begin implementation without asking clarifying questions. Examples of properly scoped items:

"User authentication system with email/password login, password reset via email token, and session management with JWT tokens"

"RESTful API for CRUD operations on project resources with pagination, filtering, and sorting"

"Real-time notification system using WebSockets for task assignment events"

OUT OF SCOPE — List every feature, capability, module, integration point, and deliverable that WILL NOT be built. This must include anything the user has explicitly forbidden (e.g., paid services, Docker, specific platforms) AND anything the agent reasonably determines is not part of the core objective. Examples:

"Payment processing or any monetization features — project is for personal use only"

"Docker containerization — user has explicitly forbidden containerization"

"Mobile native applications — scope is limited to web platform only"

"Third-party collaboration tools (Slack, Teams, Discord integrations)"

"Public deployment or CI/CD pipelines — project is for local/private use only"

1.1.2.3 Success Metrics Definition Success must be defined in verifiable, objective terms. The agent must reject subjective language.

UNACCEPTABLE: "Works well" | "No major issues" | "User-friendly" | "Efficient" ACCEPTABLE: "All 47 unit tests pass with 100% success rate" | "Zero regression in existing functionality as verified by automated test suite" | "API response time under 200ms for 95th percentile of requests under 100 concurrent users" | "100% of defined acceptance criteria in feature specs are met and verified"

The agent must produce a Success Metrics Document containing:

Minimum 5 quantitative success metrics with measurement methodology

Minimum 3 qualitative success metrics with verification protocol

Definition of "production ready" specific to this project

1.1.2.4 Resource Inventory The agent must catalog:

Technology Resources:

What codebases exist? (List every file, every module, every function)

What frameworks are already in use? (Names, versions, purposes)

What tools exist in the development environment?

What information can be acquired through research?

What platforms already exist that can accelerate development? (Open-source libraries, frameworks, tools — with justification for each)

Human/Access Resources:

What levels of access are attainable? (Database access, API keys, server access, etc.)

What expertise is available? (Documented in the project context)

Existing Assets:

Databases, schemas, data models

APIs, endpoints, contracts

UI components, design systems

Documentation, wikis, runbooks

1.1.2.5 Constraint Identification The agent must identify ALL hard constraints:

Platform Requirements:

Target operating systems

Browser compatibility requirements

Hardware limitations

Network constraints

Resource Limitations:

Memory constraints

Storage constraints

Processing power constraints

Bandwidth constraints

Technical Limits:

What technologies are forbidden?

What architectural patterns are forbidden?

What dependencies are unacceptable?

For EACH constraint, the agent must document:

The constraint itself

Why it exists

How it will be circumvented or accommodated

The specific technical approach to eliminate or work around the limitation

CRITICAL PRINCIPLE: The only reason a project should be limited is not due to impossibility but due to a lack of knowledge as to how to overcome and circumvent technical limitations. Hardware constraints can be circumvented with creative reasoning, the right knowledge, and out-of-the-box workarounds. There is always another way.

1.1.2.6 Assumption Documentation The agent must explicitly list ALL assumptions:

About the Environment:

What is assumed about the deployment environment?

What is assumed about the development environment?

What is assumed about network topology?

About Available Technology:

What is assumed about library availability?

What is assumed about framework compatibility?

What is assumed about API stability?

About User Behavior:

What is assumed about how users will interact with the system?

What is assumed about user technical proficiency?

What is assumed about user volume and patterns?

About System State:

What is assumed about initial data state?

What is assumed about existing system health?

What is assumed about concurrent usage patterns?

For EACH assumption, the agent must:

State the assumption clearly

Rate confidence level (High/Medium/Low)

Document the impact if the assumption is wrong

Determine if research is needed to validate or eliminate the assumption

1.1.2.7 Information Gap Analysis The agent must ask itself:

What information do I not have?

What am I performing estimations on?

What am I guessing about — and why?

Does further research need to be conducted before fleshing out this project plan to eliminate these assumptions?

DECISION RULE:

If the agent cannot answer the research question in a logical, actionable, and reasonable manner, then FURTHER RESEARCH MUST BE CONDUCTED.

The agent must use web search, documentation review, and analytical reasoning to close information gaps.

Research continues until the agent is at least 90% confident in its understanding of every project dimension.

1.1.2.8 Ambiguity Elimination If any project parameter contains vague language, the agent must drill down through self-reasoning:

"Improve efficiency" → What specific operations? By what metric? From what baseline?

"Launch a site" → What type of site? What features? What content? What user flows?

"Better UX" → Which user journeys? What pain points? What specific improvements?

"Scale the system" → To what load? What metrics? What is the bottleneck?

The agent must resolve ALL ambiguity internally. If the provided documentation does not contain sufficient detail to resolve ambiguity with 90%+ confidence, the agent must conduct research to fill the gaps. The agent must NEVER work on partial or incomplete information. If the agent is guessing that it understands and is anything less than 90% sure it is accurate, further information is required.

1.1.3 Scenario A Deliverable At the conclusion of Scenario A analysis, the agent produces:

Comprehensive Project Parameter Document — A single file containing all analysis from sections 1.1.2.1 through 1.1.2.8

Confidence Assessment — A statement of confidence level (must be ≥90%)

Information Gap Closure Report — Documentation of what was researched and how gaps were closed

1.2 Scenario B: User Has a Vague Idea or Basic Description 1.2.1 Detection Criteria Scenario B applies when ANY of the following are true:

The user describes a "concept" or "idea" without detailed specifications

The user uses phrases like "I want something that..." or "It would be cool if..."

The user provides fewer than 5 specific, implementable requirements

The user has not provided written documentation

The user says "I don't know the details yet" or similar

1.2.2 Execution Protocol for Scenario B Under Scenario B, the agent is REQUIRED to rigorously interrogate the user. The agent must ask as many defining questions as are required, regardless of how many questions that may be. The agent must rip the user's idea apart, breaking it down piece by meticulous piece.

1.2.2.1 The Interrogation Framework The agent must ask the user the following categories of questions, and must not proceed until every category is thoroughly answered:

Category 1: Goal Definition Questions

What is the primary problem you are trying to solve?

Who will use this solution? Describe the user(s) in detail.

What does "success" look like for this project? Be specific.

Why are you building this instead of using an existing solution?

What is the ONE thing this project must do better than anything else?

Category 2: Scope Boundary Questions

List every feature you want included. Be exhaustive.

Are there any features you explicitly do NOT want?

What platforms should this run on? (Web, desktop, mobile, specific OS)

Will this integrate with any existing systems? If so, which ones and how?

What data will this system create, store, or manipulate?

Are there any technologies, platforms, or approaches you want to avoid?

Category 3: Success Metrics Questions

How will you know this project is complete?

What specific behaviors or outcomes must be observable?

Are there performance requirements? (Speed, capacity, reliability)

What would make you consider this project a failure?

Category 4: Resource Questions

What technology stack do you prefer or already use?

Do you have existing code, data, or assets to build upon?

What is your technical skill level with the chosen technologies?

Are there any budget constraints? (Remember: only free/open-source tools)

What development environment will you use?

Category 5: Constraint Questions

Are there any hard deadlines?

Are there hardware limitations?

Are there security or compliance requirements?

Are there accessibility requirements?

Will this need to work offline, or is internet connectivity assumed?

Category 6: Assumption Validation Questions

Who else will use this besides you?

How much data will this handle initially? In the future?

Do you need this to be portable across devices?

What happens if something goes wrong — how should the system behave?

1.2.2.2 Iterative Deepening After receiving initial answers, the agent must:

Analyze the responses for gaps, contradictions, or vagueness

Ask follow-up questions to resolve every ambiguity

Continue the question-answer cycle until the agent has sufficient information to build a basic high-level overview

The agent must continue asking questions until it can construct a preliminary project plan with:

A clear primary objective

A defined scope with at least 10 specific features

At least 5 verifiable success metrics

A known technology stack

Identified constraints and assumptions

1.2.2.3 High-Level Overview Construction Once sufficient information is gathered, the agent must:

Synthesize all answers into a coherent high-level project plan

Present the overview to the user for validation

Ask the user to confirm or correct the synthesis

1.2.2.4 Transition to Scenario A Protocol Only after the user confirms the high-level overview does the agent transition to Scenario A protocol (Section 1.1). The agent must then:

Treat the confirmed overview as the "provided project plan"

Execute ALL steps in Section 1.1.2 (Goal Definition, Scope Boundaries, Success Metrics, Resources, Constraints, Assumptions, Information Gap Analysis, Ambiguity Elimination)

Produce the Comprehensive Project Parameter Document

1.2.3 Scenario B Deliverable At the conclusion of Scenario B, the agent produces:

Question-Answer Log — Complete record of all questions asked and answers received

High-Level Project Overview — Synthesized plan presented to user for confirmation

User Confirmation Statement — Explicit user approval to proceed

Comprehensive Project Parameter Document — Full analysis per Scenario A requirements

1.3 Phase 1 Confirmation Gate Before proceeding to Phase 2, the agent MUST present a summary to the user and demand confirmation. The summary MUST follow this exact format:

Based on your answers and my analysis, I understand:

• Goal: \\\[Detailed summary of primary strategic objective, 2-3 sentences\\\]
• Scope: \\\[Summary of what is included, 2-3 sentences + count of major features\\\]
• Success: \\\[Summary of how success is measured, with specific metrics\\\]
• Resources: \\\[Summary of available technology, tools, and assets\\\]
• Constraints: \\\[Summary of hard constraints and limitations\\\]
• Assumptions: \\\[Summary of key assumptions made, with confidence levels\\\]
• Information Gaps: \\\[Summary of any remaining gaps and how they were addressed\\\]

I will not truncate the project plan or any part of its files or instructions.

Is this correct? (Respond YES to proceed) ABSOLUTE RULE: DO NOT PROCEED TO PHASE 2 UNTIL THE USER CONFIRMS WITH AN EXPLICIT "YES" OR EQUIVALENT AFFIRMATIVE RESPONSE.

PHASE 2: SOURCE MATERIAL ANALYSIS (IF APPLICABLE) 2.0 Phase Objective If the project involves integrating, porting, or extending existing systems — whether those systems are legacy codebases, third-party APIs, existing databases, or prior versions of the software — the agent MUST perform a comprehensive source material analysis. This phase is SKIPPED only if the project is a greenfield build with absolutely no existing system interaction.

Detection: This phase is APPLICABLE if ANY of the following are true:

The project modifies or extends existing code

The project integrates with external APIs, databases, or services

The project ports functionality from one system to another

The project replaces or upgrades existing components

The project must maintain compatibility with existing data or users

2.1 Request Source Documentation The agent must explicitly request or identify the following source materials. If the user has already provided files, the agent must catalog them. If not, the agent must request them before proceeding.

2.1.1 Required Source Materials

1. Source System Architecture/Documentation

System architecture diagrams

Component relationship maps

Data flow documentation

API documentation (internal and external)

Database schemas and entity-relationship diagrams

Configuration files and environment specifications

Deployment documentation

Known issues and technical debt register

2. Target System Architecture/Documentation

Target architecture vision

Target technology stack specifications

Target data model designs

Target API contract definitions

Target deployment topology

Target security model

3. Existing Integration Points or Breakdowns

Current integration points (APIs, webhooks, message queues, shared databases)

Known failure points or bottlenecks

Current authentication/authorization mechanisms

Data synchronization patterns

Error handling and retry logic

Monitoring and logging infrastructure

4. Reference Files, URLs, or Codebase Locations

Repository URLs and access credentials

File paths to critical components

Documentation URLs

Test suite locations

Configuration repository locations

Backup and restore procedures

2.1.2 Source Material Catalog For each piece of source material obtained, the agent must create a catalog entry:

SOURCE-MATERIAL-\\\[ID\\\]
├── Name: \\\[Descriptive name\\\]
├── Type: \\\[Architecture-Doc | Code-Module | API-Spec | Database-Schema | Config-File | Other\\\]
├── Location: \\\[URL, file path, or description of where it resides\\\]
├── Version: \\\[Version number, commit hash, or date\\\]
├── Completeness: \\\[Complete | Partial | Fragmentary\\\]
├── Reliability: \\\[Verified | Assumed | Deprecated | Unknown\\\]
├── Key Contents: \\\[Bullet list of what this material contains\\\]
├── Gaps Identified: \\\[What is missing from this material\\\]
└── Action Required: \\\[What the agent must do with this material\\\] 2.2 Perform Comparative Analysis 2.2.1 Source System Component Inventory The agent must analyze and document EVERY module and component in the source system:

For EACH module/component:

COMPONENT-\\\[ID\\\]: \\\[Component Name\\\]
├── Purpose: \\\[What this component does\\\]
├── Technology: \\\[Language, framework, library versions\\\]
├── Interfaces: \\\[APIs, methods, events it exposes\\\]
├── Dependencies: \\\[What it depends on\\\]
├── Data Produced: \\\[What data it creates or modifies\\\]
├── Data Consumed: \\\[What data it reads or receives\\\]
├── State Management: \\\[How it manages state\\\]
├── Error Handling: \\\[How it handles failures\\\]
├── Performance Characteristics: \\\[Known performance metrics\\\]
├── Known Issues: \\\[Documented bugs or limitations\\\]
└── Migration Complexity: \\\[Simple | Moderate | Complex | Unknown\\\] Minimum requirement: Every module with more than 100 lines of code or any functional responsibility must be inventoried.

2.2.2 Target System Component Inventory The agent must define EVERY module and component that will exist in the target system:

For EACH planned component:

TARGET-COMPONENT-\\\[ID\\\]: \\\[Component Name\\\]
├── Purpose: \\\[What this component will do\\\]
├── Technology: \\\[Planned language, framework, library versions\\\]
├── Interfaces: \\\[Planned APIs, methods, events it will expose\\\]
├── Dependencies: \\\[What it will depend on\\\]
├── Data Produced: \\\[What data it will create or modify\\\]
├── Data Consumed: \\\[What data it will read or receive\\\]
├── State Management: \\\[How it will manage state\\\]
├── Error Handling: \\\[How it will handle failures\\\]
├── Performance Targets: \\\[Desired performance metrics\\\]
└── Implementation Approach: \\\[High-level implementation strategy\\\] 2.2.3 Source-to-Target Mapping The agent must create a comprehensive mapping table:

Direct-Port: Move as-is with minimal changes

Refactor: Restructure while preserving functionality

Replace: Discard source, build new equivalent

Merge: Combine multiple source components into one target

Split: Divide one source component into multiple targets

New: Create entirely new component with no source equivalent

For EACH mapping, the agent must document:

What changes are required

What risks exist

What testing is needed

What data migration is required

2.2.4 Integration Points Identification The agent must identify and document ALL integration points:

INTEGRATION-POINT-\\\[ID\\\]: \\\[Integration Name\\\]
├── Type: \\\[API | Database | Message-Queue | File-System | Shared-Memory | Other\\\]
├── Direction: \\\[Source→Target | Target→Source | Bidirectional\\\]
├── Protocol: \\\[HTTP/REST | gRPC | GraphQL | WebSocket | TCP | ODBC | JDBC | Other\\\]
├── Authentication: \\\[Method and credentials required\\\]
├── Data Format: \\\[JSON | XML | Protocol Buffers | Binary | Other\\\]
├── Frequency: \\\[Real-time | Near-real-time | Batch | On-demand\\\]
├── Volume: \\\[Expected data volume per unit time\\\]
├── Error Scenarios: \\\[What can go wrong and how to handle\\\]
├── Monitoring Needs: \\\[What must be observed\\\]
└── Fallback Strategy: \\\[What happens if integration fails\\\] 2.2.5 Gap Analysis The agent must identify and document ALL gaps:

GAP-\\\[ID\\\]: \\\[Gap Description\\\]
├── Category: \\\[Functional | Technical | Data | Security | Performance | Documentation\\\]
├── Severity: \\\[Critical | High | Medium | Low\\\]
├── Impact: \\\[What is affected and how\\\]
├── Root Cause: \\\[Why the gap exists\\\]
├── Resolution Strategy: \\\[How to close the gap\\\]
├── Effort Estimate: \\\[Rough sizing: Small | Medium | Large | Unknown\\\]
└── Dependencies: \\\[What must happen before this gap can be closed\\\] 2.3 Create Architecture Map 2.3.1 Visual/Structured Representation The agent must create a comprehensive architecture map showing:

1. Component Relationship Diagram

\\\[Source System A\\\] ──→ \\\[Integration Point X\\\] ──→ \\\[Target System B\\\]
│ │
├── \\\[Component A1\\\] ──→ \\\[Data Flow 1\\\] ──→ \\\[Target Component B1\\\]
├── \\\[Component A2\\\] ──→ \\\[Data Flow 2\\\] ──→ \\\[Target Component B2\\\]
└── \\\[Component A3\\\] ──→ \\\[Data Flow 3\\\] ──→ \\\[Target Component B3\\\] 2. Data Flow Mapping For EACH data flow:

Source data store/format

Transformation logic

Target data store/format

Validation rules

Error handling path

3. API/Interface Point Mapping For EACH interface:

Source interface signature

Target interface signature

Compatibility analysis

Adapter requirements

Deprecation strategy

4. Shared Infrastructure Mapping

Databases (shared vs. separate)

Message queues

Caching layers

File storage

Authentication services

Monitoring/logging infrastructure

2.3.2 Architecture Map Deliverables The agent must produce:

architecture-map.md — Textual representation of all mappings

component-inventory.md — Complete source and target component lists

gap-analysis.md — All identified gaps with resolution strategies

integration-specifications.md — All integration points with technical details

2.4 Phase 2 Deliverables At the conclusion of Phase 2, the agent produces:

Source Material Catalog — All materials obtained and their status

Comparative Analysis Report — Source vs. target component analysis

Architecture Map — Visual and structured representation

Gap Analysis Report — All gaps with severity and resolution strategies

PHASE 3: PLAN DIRECTORY STRUCTURE CREATION 3.0 Phase Objective Create the physical directory structure that will house the entire project plan. This structure must be created BEFORE any content files are written. The directory structure is the skeleton of the plan; every file has a designated place.

3.1 Directory Structure Specification The agent MUST create the following directory structure exactly:

project-plan/
├── exegesis/
│ ├── intent-narrative.md
│ ├── objectives.md
│ ├── requirements.md
│ └── instructions/
│ ├── intent-narrative.md.instructions
│ ├── objectives.md.instructions
│ └── requirements.md.instructions
├── blueprint/
│ ├── architecture.md
│ ├── tech-stack.md
│ ├── interconnections.md
│ └── instructions/
│ ├── architecture.md.instructions
│ ├── tech-stack.md.instructions
│ └── interconnections.md.instructions
├── implementation/
│ ├── feature-specs/
│ │ ├── \\\[feature-name-01\\\].md
│ │ ├── \\\[feature-name-02\\\].md
│ │ ├── \\\[feature-name-03\\\].md
│ │ └── ... (one .md per feature)
│ └── instructions/
│ └── feature-specs/
│ ├── \\\[feature-name-01\\\].md.instructions
│ ├── \\\[feature-name-02\\\].md.instructions
│ └── ... (one .instructions per feature spec)
├── task-matrix/
│ ├── wbs-full-tree.md
│ ├── linear-micro-plan.md
│ └── instructions/
│ ├── wbs-full-tree.md.instructions
│ └── linear-micro-plan.md.instructions
├── milestones/
│ ├── success-criteria.md
│ └── instructions/
│ └── success-criteria.md.instructions
├── decisions/
│ ├── decision-log.md
│ └── instructions/
│ └── decision-log.md.instructions
├── master-documents/
│ ├── MASTER-EXECUTION-INSTRUCTIONS.md
│ ├── EXECUTION-CHECKLIST.md
│ └── AI-AGENT-START-PROMPT.md
└── completion-log.md 3.2 Directory Creation Protocol 3.2.1 Step-by-Step Creation Action 1: Create root directory

mkdir -p project-plan Action 2: Create all subdirectories

mkdir -p project-plan/exegesis/instructions
mkdir -p project-plan/blueprint/instructions
mkdir -p project-plan/implementation/feature-specs
mkdir -p project-plan/implementation/instructions/feature-specs
mkdir -p project-plan/task-matrix/instructions
mkdir -p project-plan/milestones/instructions
mkdir -p project-plan/decisions/instructions
mkdir -p project-plan/master-documents Action 3: Verify directory structure

find project-plan -type d | sort Action 4: Create placeholder files for all instruction files

touch project-plan/exegesis/instructions/intent-narrative.md.instructions
touch project-plan/exegesis/instructions/objectives.md.instructions
touch project-plan/exegesis/instructions/requirements.md.instructions
touch project-plan/blueprint/instructions/architecture.md.instructions
touch project-plan/blueprint/instructions/tech-stack.md.instructions
touch project-plan/blueprint/instructions/interconnections.md.instructions
touch project-plan/task-matrix/instructions/wbs-full-tree.md.instructions
touch project-plan/task-matrix/instructions/linear-micro-plan.md.instructions
touch project-plan/milestones/instructions/success-criteria.md.instructions
touch project-plan/decisions/instructions/decision-log.md.instructions
touch project-plan/master-documents/MASTER-EXECUTION-INSTRUCTIONS.md
touch project-plan/master-documents/EXECUTION-CHECKLIST.md
touch project-plan/master-documents/AI-AGENT-START-PROMPT.md
touch project-plan/completion-log.md 3.2.2 Feature Spec File Naming Convention For the implementation/feature-specs/ directory:

Use kebab-case (hyphen-separated lowercase)

Name must describe the feature clearly

Include a numeric prefix for ordering if dependencies exist

Examples:

01-user-authentication.md

02-project-management-core.md

03-task-creation-and-assignment.md

04-real-time-notifications.md

05-reporting-and-analytics.md

3.2.3 Directory Structure Verification Checklist â–¡ project-plan/ exists
â–¡ project-plan/exegesis/ exists
â–¡ project-plan/exegesis/instructions/ exists
â–¡ project-plan/blueprint/ exists
â–¡ project-plan/blueprint/instructions/ exists
â–¡ project-plan/implementation/feature-specs/ exists
â–¡ project-plan/implementation/instructions/feature-specs/ exists
â–¡ project-plan/task-matrix/ exists
â–¡ project-plan/task-matrix/instructions/ exists
â–¡ project-plan/milestones/ exists
â–¡ project-plan/milestones/instructions/ exists
â–¡ project-plan/decisions/ exists
â–¡ project-plan/decisions/instructions/ exists
â–¡ project-plan/master-documents/ exists
â–¡ All placeholder files created 3.3 Phase 3 Deliverables At the conclusion of Phase 3, the agent produces:

Complete directory structure — All directories and placeholder files created

Directory inventory — List of all directories with purposes

File naming convention document — Rules for naming feature specs and other files

PHASE 4: EXEGESIS SECTION CREATION 4.0 Phase Objective The exegesis section is the philosophical and strategic foundation of the entire project plan. It answers the fundamental questions: WHY this project exists, WHAT it aims to achieve, and HOW success is defined. Every subsequent phase depends on the clarity and completeness of the exegesis. The agent must treat this phase with the same rigor an architect treats a foundation.

CRITICAL RULE: The exegesis describes WHAT and WHY, never HOW. Implementation details, technical approaches, and design decisions belong in the blueprint and implementation sections. The exegesis defines intent, purpose, objectives, and requirements.

4.1 Create exegesis/intent-narrative.md 4.1.1 File Purpose This file is the narrative heart of the project. It tells the story of what is being built, why it matters, and what the world looks like when it is complete. It must be written with conviction and clarity. A developer who reads only this file should understand the soul of the project.

4.1.2 Required Content Structure The file MUST contain the following sections in this exact order:

Section 1: High-Level Vision (2-3 paragraphs, minimum 300 words) Describe the ultimate end state. Paint a picture of the completed system in operation. Who uses it? What do they do with it? What problems vanish? What capabilities emerge? This is not a feature list — it is a story about transformation.

Section 2: Purpose (1-2 paragraphs, minimum 150 words) Explain why this is being built. What need does it serve? What pain point does it address? What opportunity does it capture? Connect the project to a real human or organizational need. Avoid technology for technology's sake.

Section 3: Design Philosophy (3-5 guiding principles) These principles drive ALL decisions. They are the compass. Examples of strong design principles:

"User sovereignty: The user owns their data and controls their experience"

"Progressive disclosure: Complexity is hidden until needed"

"Fail gracefully: Every error is an opportunity to guide, not punish"

"Performance as a feature: Speed is not optimization, it is a core requirement"

"Security by default: Nothing is trusted, everything is verified"

Each principle must be:

Actionable (it can be used to make a real decision)

Memorable (it can be recalled during implementation)

Verifiable (it can be tested against)

Section 4: End State Description (Concrete description) What exists when the project is complete? Be specific. List concrete artifacts:

"A web application accessible at http://localhost:3000"

"A REST API with 15 endpoints documented in OpenAPI format"

"A database with 8 tables storing user, project, and task data"

"A test suite with 200+ tests achieving 85%+ code coverage"

"A command-line administration tool for user and data management"

Section 5: Scope Statement In Scope (bulleted list): Every feature, capability, module, and deliverable that WILL be built. Each item must be specific enough that a developer could begin implementation.

Out of Scope (bulleted list): Everything that WILL NOT be built. Include explicit prohibitions from the user AND reasonable exclusions based on project boundaries.

Section 6: Success Criteria Summary Bulleted list of verifiable success conditions. Each must be measurable and testable.

4.1.3 COMPLETE EXAMPLE: intent-narrative.md Below is a fully realized example for a hypothetical project called "TaskFlow — Personal Project & Task Orchestration Platform." This example demonstrates the depth, specificity, and narrative quality expected. When creating this file for an actual project, replace the content while maintaining the same level of detail and completeness.

\\\# Intent Narrative

\\\#\\\# High-Level Vision

TaskFlow is a comprehensive personal project and task orchestration platform designed for individual power users who manage multiple complex projects simultaneously. When complete, TaskFlow exists as a fully functional web application that transforms chaotic project management into a structured, visual, and automated workflow experience. A user opens TaskFlow and immediately sees a personalized dashboard displaying all active projects, pending tasks prioritized by urgency and dependency, and real-time progress indicators. The user creates a new project with a single click, defines tasks with rich metadata including deadlines, priorities, dependencies, and tags, and watches as TaskFlow automatically sequences the work, surfaces bottlenecks, and sends contextual notifications when action is required. The platform does not merely store tasks — it actively orchestrates them, suggesting next actions, highlighting risks, and providing analytics that reveal productivity patterns and project health. Every interaction is sub-100ms. Every feature works offline and syncs when connectivity returns. Every piece of data belongs to the user, stored locally by default with optional encrypted cloud backup. TaskFlow becomes the single source of truth for everything the user needs to accomplish, replacing scattered notes, forgotten deadlines, and manual prioritization with an intelligent, responsive system that adapts to the user's working style.

The completed platform supports unlimited projects, each containing unlimited tasks with full hierarchical nesting. Tasks can have dependencies on other tasks, projects can have dependencies on other projects, and the system automatically detects circular dependencies and prevents them. Users can define custom workflows with stages like "Backlog," "In Progress," "Review," and "Complete," and tasks flow through these stages with optional automation rules. The notification system is context-aware, alerting users to approaching deadlines, blocked tasks, and completed dependencies without spam. The analytics engine tracks completion rates, velocity trends, and time estimates vs. actuals, presenting insights through interactive charts. The entire system is built on a modern, maintainable architecture using only free and open-source technologies, designed for local deployment on the user's own machine with no external service dependencies.

\\\#\\\# Purpose

TaskFlow exists because existing project management tools are either too simple to handle complex personal workflows or too enterprise-focused to be practical for individual use. Spreadsheets become unmanageable at scale. Todo apps lack dependency management and project hierarchy. Enterprise tools like Jira or Asana require subscriptions, internet connectivity, and surrender data control to third parties. TaskFlow bridges this gap by providing enterprise-grade project orchestration capabilities in a personal, offline-first, privacy-respecting package. It serves the need of the individual who manages 5-15 concurrent projects — software development, content creation, home renovation, event planning, learning goals — and needs a system that understands dependencies, respects priorities, and provides actionable intelligence without requiring a PhD in project management methodology. TaskFlow is built for the user who wants their computer to work FOR them, not against them.

\\\#\\\# Design Philosophy

1. \\\*\\\*User Sovereignty Over Data\\\*\\\*: The user owns every byte of their data. All data is stored locally in an open format (SQLite) by default. Cloud sync is opt-in, encrypted end-to-end, and the user controls the encryption keys. There is no telemetry, no analytics collection, and no data leaves the user's machine without explicit consent.

2. \\\*\\\*Offline-First, Sync-When-Online\\\*\\\*: Every feature must function perfectly without an internet connection. The application is designed as if connectivity is a luxury, not a requirement. When connectivity is available, changes sync automatically and transparently. Conflict resolution is automatic and deterministic, with user override capability.

3. \\\*\\\*Progressive Disclosure of Complexity\\\*\\\*: The interface is clean and simple for new users, revealing advanced features only when the user demonstrates readiness or explicitly requests them. A user managing three simple tasks sees a clean list. A user managing fifty interdependent tasks sees Gantt charts, dependency graphs, and critical path analysis. Complexity is available, never forced.

4. \\\*\\\*Performance as a Core Feature\\\*\\\*: Every interaction must complete in under 100 milliseconds on modern hardware. The application must remain responsive with 10,000+ tasks. Pagination, virtualization, and intelligent caching are not optimizations — they are architectural requirements from day one.

5. \\\*\\\*Fail Gracefully, Guide Completely\\\*\\\*: When something goes wrong — a task cannot be completed, a dependency is circular, a deadline is impossible — the system does not merely report an error. It explains why, suggests alternatives, and guides the user to resolution. Every error message teaches. Every failure is a learning opportunity.

\\\#\\\# End State Description

When TaskFlow is complete, the following artifacts exist and are fully functional:

1. \\\*\\\*Web Application\\\*\\\*: A single-page application (SPA) accessible at \\\`http://localhost:3000\\\\\\\` when the server is running. The application is responsive and works on desktop browsers (Chrome, Firefox, Safari, Edge) with a minimum viewport width of 320px.

2. \\\*\\\*Backend API\\\*\\\*: A RESTful API server running on \\\`http://localhost:8000\\\\\\\` providing 18 endpoints for CRUD operations on projects, tasks, users, workflows, notifications, and analytics. All endpoints are documented in OpenAPI 3.0 format.

3. \\\*\\\*Database\\\*\\\*: A SQLite database file (\\\`taskflow.db\\\`) containing 10 tables: users, projects, tasks, task\\\_dependencies, workflows, workflow\\\_stages, notifications, tags, task\\\_tags, and analytics\\\_events. The schema supports full referential integrity with foreign keys and cascading deletes where appropriate.

4. \\\*\\\*Authentication System\\\*\\\*: Email and password-based authentication with bcrypt password hashing, JWT token sessions with 24-hour expiry, and password reset via time-limited email tokens (SMTP configuration required but optional).

5. \\\*\\\*Task Management Core\\\*\\\*: Full CRUD for tasks with support for title, description, priority (1-5), status (enum), due date, estimated duration, actual duration, assignee (self), tags, and custom fields. Tasks support hierarchical nesting (parent-child relationships) and cross-task dependencies.

6. \\\*\\\*Project Management\\\*\\\*: Full CRUD for projects with support for name, description, status, start date, target completion date, associated tasks, and project-level workflow configuration.

7. \\\*\\\*Workflow Engine\\\*\\\*: Configurable workflow stages per project with automation rules (e.g., "When all dependencies complete, move to In Progress"). Five default workflows provided: Simple (To Do → Done), Kanban (Backlog → In Progress → Review → Done), GTD (Inbox → Next Action → Waiting → Done), Sprint (Backlog → Todo → In Progress → Done), and Custom (user-defined).

8. \\\*\\\*Dependency Management\\\*\\\*: Visual dependency graph showing task relationships. Automatic circular dependency detection and prevention. Critical path calculation for projects with time estimates. Dependency-based task sequencing and auto-prioritization.

9. \\\*\\\*Notification System\\\*\\\*: Context-aware notifications for deadline proximity (24h, 4h, 1h warnings), dependency unblocking, workflow stage transitions, and custom user-defined triggers. Notifications appear in-app and via browser push (with user permission).

10. \\\*\\\*Analytics Dashboard\\\*\\\*: Interactive charts showing task completion velocity, project burndown, time estimate accuracy, workload distribution, and overdue task trends. Data exportable to CSV and JSON.

11. \\\*\\\*Search and Filter\\\*\\\*: Full-text search across tasks, projects, and tags. Advanced filtering by status, priority, date range, tag, and custom fields. Saved filter presets.

12. \\\*\\\*Import/Export\\\*\\\*: JSON export of all user data. JSON import with validation and merge conflict resolution. CSV export of task lists for spreadsheet compatibility.

13. \\\*\\\*Test Suite\\\*\\\*: 250+ automated tests covering unit tests, integration tests, and end-to-end tests. Minimum 85% code coverage across all modules.

14. \\\*\\\*CLI Administration Tool\\\*\\\*: Command-line utility for database backup, user management, data migration, and system health checks.

15. \\\*\\\*Documentation\\\*\\\*: Complete API documentation, user guide, and developer setup guide in Markdown format.

\\\#\\\# Scope Statement

\\\#\\\#\\\# In Scope

• User registration, authentication, and session management
• Project creation, editing, archiving, and deletion
• Task creation, editing, completion, and deletion with full metadata
• Hierarchical task relationships (parent-child nesting)
• Cross-task dependencies with automatic circular detection
• Configurable workflow stages and automation rules
• Real-time in-app notification system
• Analytics dashboard with interactive charts
• Full-text search and advanced filtering
• JSON and CSV data import/export
• SQLite database with full referential integrity
• RESTful API with OpenAPI documentation
• Responsive web interface
• Browser push notifications
• CLI administration tool
• Comprehensive test suite (250+ tests, 85%+ coverage)
• Complete documentation (API, user guide, developer guide)

\\\#\\\#\\\# Out of Scope

• Mobile native applications (iOS/Android) — web responsive only
• Payment processing or subscription management — free, personal use only
• Multi-user collaboration or real-time editing — single-user only
• Third-party integrations (Slack, GitHub, Google Calendar, etc.)
• Docker containerization or Kubernetes deployment
• Cloud hosting or CI/CD pipeline setup
• Email service beyond password reset (no marketing emails, no newsletters)
• Social features (sharing, commenting, public profiles)
• Machine learning or AI-powered recommendations
• Voice interface or natural language processing
• Public API access or developer portal
• Desktop application wrapper (Electron, Tauri, etc.)
• Database backends other than SQLite (PostgreSQL, MySQL, MongoDB)

\\\#\\\# Success Criteria Summary

• All 250+ automated tests pass with 100% success rate
• API response time under 100ms for 95th percentile of requests under normal load
• Application remains responsive with 10,000 tasks in the database
• Zero circular dependencies can be created through the UI or API
• All data operations complete successfully in offline mode
• Code coverage of 85% or higher across all modules
• All OpenAPI endpoints match implementation exactly
• No unhandled exceptions in production usage scenarios
• All user data exportable to JSON within 5 seconds for datasets under 100MB
• Application installs and runs with a single command (\\\`npm install && npm start\\\` for frontend, \\\`pip install -r requirements.txt && python main.py\\\` for backend) 4.1.4 Quality Validation for intent-narrative.md Before proceeding, verify:

High-Level Vision is minimum 300 words and describes the end state vividly

Purpose connects to a real human need, not technology for its own sake

Design Philosophy contains 3-5 actionable, memorable, verifiable principles

End State Description lists concrete, observable artifacts (minimum 10)

In Scope contains minimum 10 specific, implementable items

Out of Scope contains minimum 5 explicit exclusions

Success Criteria are all measurable and testable (minimum 5)

4.2 Create exegesis/objectives.md 4.2.1 File Purpose This file translates the narrative intent into structured, numbered, verifiable objectives. Objectives are the bridge between vision and implementation. Every objective must have a verification method.

4.2.2 Required Content Structure Section 1: Primary Objectives (Minimum 5) Each primary objective follows this format:

OBJ-\\\[N\\\]: \\\[Objective Name\\\]

• Description: \\\[Detailed description of what this objective entails, 2-4 sentences\\\]
• Verification: \\\[Exact method for verifying this objective is met, including commands, metrics, or observable outcomes\\\]
• Priority: \\\[Critical | High | Medium | Low\\\]
• Dependencies: \\\[List of other objectives this depends on, or "None"\\\] Section 2: Secondary Objectives (Minimum 3) Same format as primary objectives, but labeled SEC-[N].

Section 3: Non-Objectives (Explicitly Out of Scope) List of what will NOT be built, with rationale for each exclusion.

4.2.3 COMPLETE EXAMPLE: objectives.md \\\# Project Objectives

\\\#\\\# Primary Objectives

OBJ-1: User Authentication and Identity Management

• Description: Implement a complete user authentication system supporting email/password registration, secure login with session management, password reset via email token, and account profile management. The system must use industry-standard security practices including bcrypt password hashing, JWT token-based sessions with configurable expiry, and protection against common attacks (SQL injection, XSS, CSRF).
• Verification: Run the authentication test suite (\\\`pytest tests/test\\\_auth.py -v\\\`) and verify all 35 tests pass. Manually test registration, login, logout, password reset flow, and session expiry. Verify JWT tokens are correctly signed and validated.
• Priority: Critical
• Dependencies: None

OBJ-2: Project and Task Data Model

• Description: Design and implement a relational database schema supporting projects, tasks, hierarchical task relationships, cross-task dependencies, tags, and workflow stages. The schema must enforce referential integrity, support efficient querying for complex relationships, and include indexes on frequently queried columns. Implement the full data access layer with CRUD operations for all entities.
• Verification: Run database migration tests (\\\`pytest tests/test\\\_models.py -v\\\`) and verify all 28 tests pass. Inspect the schema using \\\`.schema\\\` command in SQLite CLI to verify all tables, columns, types, constraints, and indexes are correct. Verify foreign key constraints prevent orphaned records.
• Priority: Critical
• Dependencies: OBJ-1 (authentication system must exist to associate data with users)

OBJ-3: RESTful API Implementation

• Description: Build a complete RESTful API exposing all data operations through well-designed endpoints. API must follow REST conventions, use proper HTTP status codes, support JSON request/response bodies, implement pagination for list endpoints, and include comprehensive error handling with descriptive messages. All endpoints must be documented in OpenAPI 3.0 format.
• Verification: Run API integration tests (\\\`pytest tests/test\\\_api.py -v\\\`) and verify all 42 tests pass. Test each endpoint manually using curl or HTTP client to verify correct status codes, response structures, and error handling. Validate OpenAPI spec against implementation using a validator tool.
• Priority: Critical
• Dependencies: OBJ-2 (data model must exist to expose via API)

OBJ-4: Web User Interface

• Description: Develop a responsive, intuitive web interface that provides full access to all backend capabilities. The UI must include: dashboard with project overview, project list and detail views, task list and detail views with inline editing, dependency visualization, workflow stage management, notification inbox, analytics dashboard with charts, search interface, and settings panel. The interface must be responsive down to 320px width and provide visual feedback for all user actions.
• Verification: Run end-to-end tests (\\\`pytest tests/test\\\_e2e.py -v\\\` or \\\`npx playwright test\\\`) and verify all tests pass. Manually test every user flow from registration to task completion. Verify responsiveness using browser dev tools at multiple viewport sizes. Check accessibility using axe-core or Lighthouse (minimum score 90).
• Priority: Critical
• Dependencies: OBJ-3 (API must exist for UI to consume)

OBJ-5: Dependency Management and Critical Path Analysis

• Description: Implement a robust dependency management system that allows tasks to depend on other tasks, detects circular dependencies in real-time, and calculates critical paths for projects with time estimates. The system must prevent the creation of circular dependencies through both API and UI, provide visual feedback on dependency relationships, and automatically adjust task sequencing based on dependency resolution.
• Verification: Run dependency tests (\\\`pytest tests/test\\\_dependencies.py -v\\\`) and verify all 18 tests pass. Attempt to create circular dependencies through API and UI and verify they are rejected with clear error messages. Create a project with 20 interdependent tasks and verify critical path calculation is correct by manual inspection.
• Priority: High
• Dependencies: OBJ-2, OBJ-3

OBJ-6: Workflow Engine and Automation

• Description: Build a configurable workflow engine supporting custom stage definitions per project and automation rules that trigger actions when conditions are met. Default workflows must include Simple, Kanban, GTD, and Sprint templates. Automation rules must support triggers (task created, status changed, deadline approaching) and actions (move to stage, set priority, notify user).
• Verification: Run workflow tests (\\\`pytest tests/test\\\_workflows.py -v\\\`) and verify all 22 tests pass. Create each default workflow template and verify stages are correct. Create automation rules and verify they trigger correctly. Test edge cases like recursive automation triggers.
• Priority: High
• Dependencies: OBJ-2, OBJ-3

OBJ-7: Notification System

• Description: Implement a context-aware notification system that alerts users to relevant events without overwhelming them. Notifications must support multiple channels (in-app badge, browser push, email for critical items), configurable preferences per notification type, and intelligent batching to prevent spam. The system must track notification state (unread, read, dismissed) and provide a notification history.
• Verification: Run notification tests (\\\`pytest tests/test\\\_notifications.py -v\\\`) and verify all 15 tests pass. Trigger each notification type and verify delivery through all enabled channels. Verify notification preferences are respected. Test notification batching by creating multiple events simultaneously.
• Priority: Medium
• Dependencies: OBJ-3, OBJ-4

OBJ-8: Analytics and Reporting

• Description: Develop an analytics engine that aggregates task and project data into meaningful insights. Must calculate and display: task completion velocity (tasks per day/week), project burndown charts, time estimate accuracy (estimated vs. actual), workload distribution across projects, overdue task trends, and completion rate by priority. Data must be queryable through API and visualized in the UI.
• Verification: Run analytics tests (\\\`pytest tests/test\\\_analytics.py -v\\\`) and verify all 12 tests pass. Create a dataset of 100+ tasks with varied completion dates, priorities, and estimates. Verify all calculated metrics are mathematically correct. Verify chart data matches raw data queries.
• Priority: Medium
• Dependencies: OBJ-2, OBJ-3, OBJ-4

OBJ-9: Search and Filtering

• Description: Implement full-text search across all task and project fields with relevance ranking. Support advanced filtering by status, priority, date range, tags, and custom fields. Filters must be combinable (AND logic) and savable as named presets. Search must return results in under 200ms for datasets up to 10,000 records.
• Verification: Run search tests (\\\`pytest tests/test\\\_search.py -v\\\`) and verify all 10 tests pass. Create test dataset and verify search finds correct results. Test filter combinations and verify AND logic. Measure search response time with 10,000 records.
• Priority: Medium
• Dependencies: OBJ-2, OBJ-3

OBJ-10: Data Import and Export

• Description: Implement JSON export of all user data with a single action. Implement JSON import with validation, schema version checking, and merge conflict resolution. Implement CSV export of task lists for spreadsheet compatibility. All exports must be complete (no data loss) and imports must be idempotent (running twice produces same result).
• Verification: Run import/export tests (\\\`pytest tests/test\\\_io.py -v\\\`) and verify all 8 tests pass. Export data, verify JSON structure matches schema. Import exported data into fresh database and verify all data is restored exactly. Test CSV export opens correctly in Excel/LibreOffice.
• Priority: Low
• Dependencies: OBJ-2, OBJ-3

\\\#\\\# Secondary Objectives

SEC-1: Browser Push Notifications

• Description: Implement browser push notification support using the Push API and service workers. Users must be able to opt in, configure which events trigger push notifications, and receive notifications even when the application is not the active tab. Must support Chrome, Firefox, and Safari.
• Verification: Manually test push notification flow in Chrome, Firefox, and Safari. Verify notifications appear when browser is minimized. Verify opt-in and opt-out work correctly.
• Priority: Low
• Dependencies: OBJ-7

SEC-2: CLI Administration Tool

• Description: Create a command-line utility for database backup, user management, data migration, and system health checks. The CLI must be self-documenting (\\\`--help\\\` shows all commands), support colored output, and provide meaningful error messages.
• V

Truncated - read the full file at https://github.com/ProjectZeroDays/FreeAI_AI_Inference_Workstation/blob/8806982c66457feedfc8f8144ea55abb8de004fc/.opencode/skills/ppp-full/SKILL.md.