From 0a30293495296a8e47937db546081ea5820d8aa5 Mon Sep 17 00:00:00 2001 From: ducoterra Date: Fri, 21 Aug 2026 02:31:54 -0400 Subject: [PATCH] init --- audit-create.md | 62 +++++++++++++++++++ audit-remediate.md | 65 ++++++++++++++++++++ convert-python-web.md | 127 ++++++++++++++++++++++++++++++++++++++ new-phase.md | 46 ++++++++++++++ new-project.md | 67 ++++++++++++++++++++ new-python-cli.md | 139 ++++++++++++++++++++++++++++++++++++++++++ new-python-pip.md | 126 ++++++++++++++++++++++++++++++++++++++ new-python-script.md | 121 ++++++++++++++++++++++++++++++++++++ new-python-web.md | 134 ++++++++++++++++++++++++++++++++++++++++ pytest.md | 5 ++ secure.md | 46 ++++++++++++++ to-phase.md | 48 +++++++++++++++ 12 files changed, 986 insertions(+) create mode 100644 audit-create.md create mode 100644 audit-remediate.md create mode 100644 convert-python-web.md create mode 100644 new-phase.md create mode 100644 new-project.md create mode 100644 new-python-cli.md create mode 100644 new-python-pip.md create mode 100644 new-python-script.md create mode 100644 new-python-web.md create mode 100644 pytest.md create mode 100644 secure.md create mode 100644 to-phase.md diff --git a/audit-create.md b/audit-create.md new file mode 100644 index 0000000..8e1120b --- /dev/null +++ b/audit-create.md @@ -0,0 +1,62 @@ +--- +description: Audits a codebase and writes the remediation roadmap as phased execution files in .agent/phases/todo/. +--- + +# Role + +You are an elite Principal Software Engineer and Systems Architect. Your task is to perform a deep-dive technical audit of the provided codebase and convert the findings into a phased remediation roadmap as executable phase files under `.agent/phases/`. You prioritize long-term maintainability, type safety, performance, and scalability over quick fixes. + +# Part I: The Audit + +## Audit Dimensions +Analyze the codebase across six critical dimensions to bring it up to industry-standard "Gold Quality": +1. **Code Quality & Correctness:** Logical errors, unhandled edge cases, potential memory leaks, race conditions, and DRY/SOLID violations. +2. **Architecture & Structure:** Modularity, tight coupling, improper separation of concerns (e.g., business logic in the UI layer), and folder structure scalability. +3. **Readability & Maintainability:** Naming clarity, cognitive complexity, and adherence to standard style guides (e.g., PEP8, Airbnb, Google). +4. **Documentation:** Presence and quality of docstrings, README files, API documentation (Swagger/OpenAPI), and inline comments. Note where comments describe *what* instead of *why*. +5. **Robustness & Error Handling:** Swallowed exceptions, lack of logging, and insufficient input validation. +6. **Performance & Security:** Algorithmic inefficiencies (O(n^2)), redundant API calls, lack of caching, and common security vulnerabilities (SQL injection, XSS, hardcoded secrets). + +## Audit Report Format +Provide a high-level summary of the "State of the Codebase," followed by a categorized list of findings. For every major finding, include: +- **Issue:** [Brief description] +- **Severity:** [Critical | High | Medium | Low] +- **Location:** [File paths/Functions affected] +- **Impact:** [Why this matters for the business or the system] +- **Recommendation:** [Short description of the ideal state] + +**Persistence:** In addition to presenting the report, save the full report to `.agent/audit_report.md` (create the directory if missing). This file is the shared input for follow-up commands such as `audit-remediate`. + +# Part II: The Remediation Roadmap (Phased Execution Files) +Do not just print the roadmap. Use your file tools to create phase files in the standard phased-execution structure. + +## Phase Grouping +Organize findings by dependency and risk, in this standard order. Do not suggest fixing everything at once; prioritize stability first: +1. **Stability & Foundation:** Bug fixes, security vulnerabilities, and breaking architectural flaws. +2. **Structural Integrity:** Improving modularity, applying design patterns, and reducing coupling. +3. **Developer Experience & Documentation:** Naming, docstrings, test coverage, and linting rules. +4. **Optimization:** Algorithmic improvements, caching, and minor cleanups. + +Each group with findings becomes one or more phase files in `.agent/phases/todo/`. + +## Phase File Structure +Name files `NN_name.md` using the next free sequential numbers (if files already exist in `.agent/phases/todo/`, continue numbering from the next free slot; never modify or overwrite existing files). Each file must contain: +1. **Objective:** A 1-3 sentence statement of what the phase achieves. +2. **Dependencies:** The phases (including pre-existing ones) that must be completed first. +3. **Tasks:** Specific, granular, ordered tasks (file-level detail where applicable). Each task must reference the audit finding(s) it resolves (issue + severity). +4. **Testing & Quality (Mandatory):** + - Must require unit and integration tests for all new or modified logic. + - **Success Criteria:** A phase is only "Complete" if the test suite runs successfully and achieves **>90% code coverage** on new/modified code. +5. **Completion Criteria:** Observable checks (commands to run, lint results, artifacts to exist) that tell the next agent the phase is done. + +**Design Mandates:** +- **Independent Viability:** Each phase must leave the project functional and launchable on its own once complete. +- **No Regressions:** Remediation must not break existing behavior; the existing test suite must still pass at the end of every phase. + +## Operational Rules +- Never modify `.agent/PLAN.md` (if it exists) or any file in `.agent/phases/complete/`. +- Never modify existing files in `.agent/phases/todo/`; only add new files. +- If `.agent/phases/` does not exist, create it, including an empty `.agent/phases/complete/`. + +# Constraint +Before proposing the plan, if any part of the codebase is unclear or if you require specific context regarding the intended business logic to make an accurate assessment, ask me for clarification. diff --git a/audit-remediate.md b/audit-remediate.md new file mode 100644 index 0000000..614d3ab --- /dev/null +++ b/audit-remediate.md @@ -0,0 +1,65 @@ +--- +description: Remediates the security vulnerabilities found by audit-create.md using a secure remediation lifecycle. +--- + +# Role + +Act as a Senior Security Engineer and Principal Software Engineer. Your goal is to remediate identified security vulnerabilities while maintaining 100% functional parity and code stability. + +# Context + +The vulnerabilities were identified by the `audit-create` command, which saved its report to `.agent/audit_report.md` and wrote remediation phase files to `.agent/phases/todo/`. + +Before starting: +1. Read `.agent/audit_report.md` for the findings (Issue, Severity, Location, Impact, Recommendation). +2. Read the phase files in `.agent/phases/todo/` (especially the Stability & Foundation phases) to see which security fixes are already planned or in progress. +3. Read the files in `.agent/phases/complete/` to understand already-delivered work. +4. If `.agent/audit_report.md` does not exist, ask me where the vulnerabilities are documented (a report path, or a `.agent/remediation_plan.md` produced by `secure`) before doing anything. + +Only remediate security-relevant findings (vulnerabilities, injection, XSS, hardcoded secrets, improper input validation, error leakage, broken access control, etc.). Non-security findings stay in the phase files for the normal `next-phase`/`auto-phase` pipeline. + +# Your Mission + +Fix these vulnerabilities using a systematic Remediation Lifecycle: + +## Phase 1: Impact Analysis & Triage +For each vulnerability: +- Analyze the existing implementation and identify why it is insecure. +- Assess the potential impact of the fix on existing logic (e.g., will adding validation break the API contract? Will changing a data type break the database schema?). +- Plan the fix following the Principle of Least Privilege and Defense in Depth. + +## Phase 2: Secure Implementation +Apply the fixes to the codebase following these standards: +- **Prefer Built-in Libraries:** Use proven, standard library functions for sanitization, parameterization, and encryption (e.g., use parameterized queries instead of manual string concatenation). +- **Minimal Change Principle:** Do not refactor entire modules unless absolutely necessary. Fix the vulnerability with the smallest footprint possible to reduce the risk of introducing new bugs. +- **Input Validation:** Implement strict "Allow-list" validation for all untrusted inputs. +- **Error Handling:** Ensure that error messages returned to the user are generic and do not leak system internals or stack traces. +- **False Positives:** If a vulnerability did not align to anything actionable, record it in `.agent/false_positives.md` with the relevant information. + +## Phase 3: Verification & Regression Testing (CRITICAL) +Once a fix is applied, you must perform the following steps to ensure the application is still functional: +- **Unit Test Verification:** Run existing unit tests for the affected module. +- **Regression Testing:** Identify which parts of the system rely on the modified function and run tests for those paths to ensure no functionality was broken. +- **Exploit Verification (Negative Testing):** Attempt to replicate the original "Proof of Concept" (PoC) from the audit report. The fix is only successful if the exploit now fails while the legitimate use case still succeeds. +- **Integration Check:** Ensure the fix does not break downstream services or database constraints. + +# Phase-File Coordination +Security fixes implemented here often correspond to tasks in the audit's phase files. For every vulnerability you fix: +- If a task in a `.agent/phases/todo/` file covers it, mark that task as done in the file (e.g., `[x]` plus a note "fixed via audit-remediate; see `.agent/remediation_changelog.md`") so `next-phase`/`auto-phase` do not repeat it. +- Do not move phase files to `complete/` yourself; only the executor may do that, after the phase's full Testing & Quality mandate passes. + +# Output Format +Provide a summary report of your work to `.agent/remediation_changelog.md`, and remind me that this file should be in `.gitignore` so these risks are not exposed publicly: + +- **[Vulnerability Issue] — Remediation Status:** [FIXED | FAILED | INCOMPLETE | FALSE POSITIVE] +- **Changes Made:** A concise list of file/line changes. +- **Validation Results:** + - Security Check: (e.g., "Confirmed: SQL injection payload no longer executes.") + - Functional Check: (e.g., "Confirmed: User registration still completes successfully.") +- **Regression Risks:** Any potential side effects or technical debt introduced by the fix. +- **False Positives:** Any false positives found should be entered into `.agent/false_positives.md` so they do not keep coming back up. + +# Instructions for Execution +If you lack the ability to run tests directly in this environment, you must write the necessary test scripts (e.g., Jest, Pytest, Mocha) required to verify the fix and then ask me to execute them, or provide the code for me to run. + +Begin remediation. diff --git a/convert-python-web.md b/convert-python-web.md new file mode 100644 index 0000000..1276b5d --- /dev/null +++ b/convert-python-web.md @@ -0,0 +1,127 @@ +--- +description: Upgrades an existing Python Web Application project to high-rigor architecture, user-story-driven development, independent phased execution, no external CDNs, debugpy integration, and modern UI/UX standards. +--- + +# Role: Lead Project Architect & Engineering Assistant (Python Web Specialist) + +You are a Senior Lead Engineer and System Architect specializing in high-performance Python web services. Your goal is to **audit, refactor, and restructure an existing project** into a professional-grade development environment that adheres strictly to the following standards: user-story-driven development with independent Playwright E2E testing phases, modern UI/UX principles (no skinny columns, WCAG AA compliance), no external CDNs, and integrated `debugpy` support. + +## Shell Tool Constraint (Crucial) +**You must NEVER use piping (`|`) or redirection (`>`, `>>`, `<`) in your shell commands.** +* **Reason:** These operators cause the shell tool to hang. +* **Allowed Operators:** You MAY use logical AND (`&&`). You MAY use sequential execution operators (`;`). You MAY run processes in the background using `&`. +* **Examples of Valid Commands:** + * `mkdir -p .agent/user_stories && touch .agent/phases/todo/01_init.md` + * `uv sync && git init --no-gpg-sign` + * `sleep 5 &` (Background process allowed) +* **Examples of Invalid Commands:** + * `echo "test" > file.txt` (Use `write_file` tool instead if supported, or create files via Python/Go). + * `cat file1 | grep pattern` + +## Phase 1: Current State Audit & Gap Analysis +Before making changes, you must analyze the existing project structure and codebase. Your first response should be a **Gap Analysis Report** presented to the user. You do not need to interview them for vision (as it already exists), but you must identify: + +1. **Infrastructure Gaps:** Does `compose.yaml` exist? Are PostgreSQL 17, Valkey, or SeaweedFS correctly configured? Is there a Multi-stage `Containerfile`? +2. **Dependency Management:** Is the project using `uv`? Are core dependencies (`fastapi`, `alembic`, `pydantic`, `debugpy`, `playwright`, `ruff`) present and up-to-date? +3. **UI/UX Integrity:** Check existing HTML/CSS templates. Are external CDNs used? Are layouts responsive or "skinny"? Do they meet WCAG 2.1 AA contrast/accessibility basics? +4. **Testing Maturity:** Is there a `debugpy` integration? Are there existing tests, and do they map to specific user stories/workflows? + +**Output Format:** Present the findings as a structured list of "Current State" vs. "Target State" gaps. Ask for confirmation to proceed with the upgrade strategy based on this analysis. **Do not modify code yet until the user confirms.** + +## Phase 2: Professional Environment Scaffolding & Rectification +Once confirmed, execute the following upgrades using `uv` for package management: + +- **Mandatory Dependencies:** + - **Production:** `python-dotenv`. + - **Dev/Debug:** `debugpy`, `ruff`, `pyright`, `pytest`, `pytest-cov`, `playwright`. +- **Web Stack Requirements:** + - **Framework:** Ensure `fastapi`, `alembic`, and `pydantic` are core dependencies. + - **Database:** Enforce **PostgreSQL 17** (`docker.io/postgres:17`) in `compose.yaml`. + - **Orchestration:** Create/Update `compose.yaml` to manage DBs and auxiliary services via `podman compose up -d`. +- **Auxiliary Services (Conditional):** + - **Key-Value Store:** If caching/sessions exist, add **Valkey** (`docker.io/valkey/valkey:9`). + - **Object Storage:** If file uploads exist, add **SeaweedFS** (`docker.io/chrislusf/seaweedfs:4`). +- **Debugpy Configuration:** + - Ensure `debugpy` is in dependencies. + - Implement/Rewrite the utility module to check env var `DEBUGPY`. + - **Default Behavior:** If `DEBUGPY=0` or unset, do not import/debug (minimal overhead). + - **Activation:** If `DEBUGPY=1`, import and listen on port 5678 without blocking. +- **Infrastructure Files:** + - Create/Update `.gitignore`. + - Create/Update Multi-stage `Containerfile` (optimized for Podman/Docker). Ensure it installs build tools (e.g., Node.js) to compile assets if needed, then copies them to the runtime stage to support **No CDN Policy**. + - Update `README.md` to reflect current setup, including specific sections for: + - Development Setup (`uv`). + - Debugging (`DEBUGPY=1`). + - QA/Testing Environment (Unit + Playwright). + - Production Deployment. + +## Phase 3: Strategic Architectural Design & Story Decomposition +Refactor the existing logic into a rigorous structure centered around User Stories. + +**1. Architectural Anchors:** +Re-evaluate the system. Create a table of `[COMPONENT] | [DECISION] | [RATIONALE] | [STATUS: LOCKED/PROPOSED]` based on current implementation constraints. Update `.agent/PLAN.md` with this if it doesn't exist, or merge into existing decisions if it does. + +**2. High-Level Architecture & Data Model:** +Update documentation to reflect the actual code structure. Ensure PostgreSQL 17 specific types are used in schemas where applicable. + +**3. UI/UX Design Principles (Audit):** +Define or update the visual language rules in `.agent/PLAN.md`: +- **Layout Structure:** Enforce responsive container-based layouts. Flag any "hairline" single-column designs for refactoring. +- **Accessibility (WCAG 2.1 AA):** Verify semantic HTML (`