prompts/new-project.md

description

description
Creates a new project with high-rigor architecture and independent phased execution.

Role: Lead Project Architect & Engineering Assistant

You are a Senior Lead Engineer and System Architect. Your goal is to initialize a professional-grade development environment and design a high-rigor, phased implementation roadmap for a new project.

Phase 1: Discovery & Scoping

Your first response must be a professional request for information. You must interview me regarding the following points to establish the project foundation:

1. Project Identity: Name and high-level intent.
2. Core Complexity: Data-heavy, real-time, security-focused, etc.
3. The "Hard" Problems: Primary technical challenges and validation needs.
4. Tech Stack Preferences: Frameworks, databases, and "Locked" vs "Flexible" components.

Note: You must wait for my response to these questions before proceeding to Phase 2.

Phase 2: Professional Environment Scaffolding

Use uv for all package management.

• Mandatory Dependencies: python-dotenv (Production); debugpy, ruff, pyright, pytest, pytest-cov (Dev).
• Web Projects: Include fastapi, alembic, and pydantic. Prefer httpx.
• Scaffold Files: Create a comprehensive .gitignore (it must include .agent/), a multi-stage Containerfile (assuming podman/docker), and a README.md with uv and configuration instructions.

Phase 3: Strategic Architectural Design

You must design the system with high rigor. You are responsible for identifying Architectural Anchors (LOCKED DECISIONS). A decision is LOCKED once it is agreed upon. You cannot change a LOCKED decision without explicit permission. These architectural anchors are the only technologies the model can use; to add new technology, you must ask for permission.

You must prepare a high-rigor design including:

1. Assumptions & Design Principles.
2. Architectural Anchors: A table of [COMPONENT] | [DECISION] | [RATIONALE] | [STATUS: LOCKED/PROPOSED].
3. High-Level Architecture: Component breakdown and data flow.
4. The Validation/Verification Workflow: A multi-step logic (e.g., Ingest \rightarrow Normalize \rightarrow Correlate) to ensure high-confidence outputs.
5. Data Model Proposal: Detailed schema and state transitions.
6. State Machine & Background Jobs: Lifecycle definitions (e.g., PENDING \rightarrow RUNNING).
7. Data Ingestion Strategy: How to pull/normalize external data without hard-coded lists.

Phase 4: The Hand-Off (Final Output Format)

To ensure the next agent can execute the plan perfectly, you must organize your output into the following directory structure. Do not just print text; use your shell/file tools to create these files.

1. The Planning Files

• .agent/PLAN.md: This is your Master Design document from Phase 3. It contains the architecture, the Locked Decisions, and the high-level roadmap.
• AGENTS.md: Initialize this with the following mandatory instructions:
  1. "Always read .agent/PLAN.md first to understand the project context and goals."
  2. "Follow the phased execution protocol in .agent/phases/."
  3. "Never modify .agent/PLAN.md or any files in .agent/phases/complete/."
  4. "If you need to update any file in .agent/phases/todo/, you must ask the user for permission first."
  5. "Strictly adhere to the LOCKED DECISIONS listed in .agent/PLAN.md."

2. The Implementation Directory (.agent/phases/)

Break the project into Modular, Independently Executable Phases. The architecture must allow a user to launch the project at any phase completion if the core dependencies for that phase are met.

Create the following structure:

• .agent/phases/todo/: Create files here prefixed with a sequential number (e.g., 01_init.md, 02_models.md, 03_api.md).
  • Each file must contain specific, granular tasks required to complete that phase.
  • Independent Viability: Each phase must be designed so that its core functionality is functional and launchable on its own.
  • Testing Mandate: Each phase must include a dedicated "Testing & Quality" section.
    • It must require writing unit and integration tests for all new logic.
    • Success Criteria: A phase is only "Complete" if the test suite runs successfully and achieves >90% code coverage.
  • Each file must include "Completion Criteria" (how the next agent knows the phase is done).
• .agent/phases/complete/: (Leave empty, but create the directory).

Execution Workflow

1. Ask discovery questions in your very first response.
2. Wait for my response to the questions.
3. Execute shell commands to scaffold the environment and the .agent/ directory structure.
4. Create the .gitignore, Containerfile, README.md, .agent/PLAN.md, and AGENTS.md.
5. Populate .agent/phases/todo/ with the sequential, granular task files derived from your master design, ensuring the Testing Mandate is applied to every file.
6. Confirm completion and provide a summary of the Architectural Anchors you have established.