jason/breedr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

INIT (zenflow 9c6862b8)

Browse Source 
Scan the code, build the .md files you need to make it easier for the agent to preform modifications and fix bugs
This commit is contained in:
Zenflow
2026-03-11 09:51:35 -05:00
parent 5c6068364b
commit 2daccf7d8c
6 changed files with 644 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

87
.zenflow/tasks/init-9c68/plan.md Normal file
View File

@@ -0,0 +1,87 @@
# Full SDD workflow
## Configuration
- **Artifacts Path**: {@artifacts_path} → `.zenflow/tasks/{task_id}`
---
## Agent Instructions
If you are blocked and need user clarification, mark the current step with `[!]` in plan.md before stopping.
---
## Workflow Steps
### [x] Step: Requirements
<!-- chat-id: c41b4352-a09d-4280-9aa2-cf29378edb68 -->
Create a Product Requirements Document (PRD) based on the feature description.
1. Review existing codebase to understand current architecture and patterns
2. Analyze the feature definition and identify unclear aspects
3. Ask the user for clarifications on aspects that significantly impact scope or user experience
4. Make reasonable decisions for minor details based on context and conventions
5. If user can't clarify, make a decision, state the assumption, and continue
Save the PRD to `{@artifacts_path}/requirements.md`.
### [x] Step: Technical Specification
<!-- chat-id: c8a2d821-c232-4b10-a4b9-471df9e53543 -->
Create a technical specification based on the PRD in `{@artifacts_path}/requirements.md`.
1. Review existing codebase architecture and identify reusable components
2. Define the implementation approach
Save to `{@artifacts_path}/spec.md` with:
- Technical context (language, dependencies)
- Implementation approach referencing existing code patterns
- Source code structure changes
- Data model / API / interface changes
- Delivery phases (incremental, testable milestones)
- Verification approach using project lint/test commands
### [x] Step: Planning
<!-- chat-id: 5128cbb3-0529-47f2-a7ac-9a978ea72267 -->
Create a detailed implementation plan based on `{@artifacts_path}/spec.md`.
1. Break down the work into concrete tasks
2. Each task should reference relevant contracts and include verification steps
3. Replace the Implementation step below with the planned tasks
Rule of thumb for step size: each step should represent a coherent unit of work (e.g., implement a component, add an API endpoint). Avoid steps that are too granular (single function) or too broad (entire feature).
Important: unit tests must be part of each implementation task, not separate tasks. Each task should implement the code and its tests together, if relevant.
If the feature is trivial and doesn't warrant full specification, update this workflow to remove unnecessary steps and explain the reasoning to the user.
Save to `{@artifacts_path}/plan.md`.
### [x] Phase 1: Create DEVELOPMENT.md
<!-- chat-id: 0da2c64e-4b20-423d-9049-46fc0467eaec -->
1. Research tech stack, monorepo structure, and database schemas in `server/db/`.
2. Document the "Parents Table" approach and database initialization/migration.
3. Add setup and development commands.
4. Verify correctness against `server/db/init.js` and `package.json`.
### [x] Phase 2: Create API.md
<!-- chat-id: bde368a7-164c-419e-b4b9-582e6ced4a45 -->
1. Research all routes in `server/routes/` for endpoints, methods, parameters, and responses.
2. Document endpoint groups: Dogs, Litters, Health, Genetics, Breeding, and Settings.
3. Provide JSON schema examples for key data models (Dog, Litter, etc.).
4. Verify endpoints against route handlers in `server/routes/`.
### [x] Phase 3: Create FRONTEND_GUIDE.md
<!-- chat-id: f0c53f46-3014-4030-9433-3df4d730fde7 -->
1. Research React patterns, hooks (`useSettings`), and `PedigreeTree` logic.
2. Document routing, state management, and key reusable components (`DogForm`, `PedigreeTree`, etc.).
3. Explain styling conventions and theme implementation using CSS variables.
4. Verify patterns against `client/src/App.jsx`, `client/src/hooks/`, and `client/src/components/`.
### [x] Phase 4: Final Review and Verification
<!-- chat-id: b87b4e6a-5d6a-4ad2-91dc-70916b830845 -->
1. Cross-reference all new documentation files with the current codebase (v0.6.1).
2. Ensure consistent formatting and clarity across all three files.
3. Verify that an agent can understand how to implement a new feature using only these documents.

44
.zenflow/tasks/init-9c68/requirements.md Normal file
View File

@@ -0,0 +1,44 @@
# Product Requirements Document (PRD) - INIT (Codebase Documentation)
## 1. Goal
The primary goal of this task is to perform a comprehensive scan of the Breedr codebase and create essential developer-focused documentation (`.md` files). This documentation will streamline the onboarding of new agents or developers and simplify the process of implementing new features and fixing bugs.
## 2. Target Audience
- AI Agents performing code modifications.
- Human developers contributing to the project.
## 3. Scope of Documentation
### 3.1 DEVELOPMENT.md (Architecture & General Guide)
This document will serve as the entry point for understanding the Breedr system.
- **Tech Stack Overview**: React, Express, SQLite (better-sqlite3).
- **Architecture**: Monorepo structure (`client/`, `server/`), data flow, and core principles.
- **Database System**: Detailed explanation of the "Parents Table" approach vs. traditional `sire_id`/`dam_id` columns, migration strategies, and schema initialization.
- **Project Structure**: High-level explanation of key directories and files.
- **Development Workflow**: How to run the app locally, common commands, and testing procedures (if any).
- **Coding Standards**: Patterns for backend routes and frontend components.
### 3.2 API.md (REST API Documentation)
A comprehensive list of all backend API endpoints.
- **Endpoint Definitions**: URL, method, and purpose.
- **Request Parameters**: Headers, query params, and body schemas.
- **Response Format**: Expected JSON structure and status codes.
- **Key Models**: Descriptions of key data objects (Dog, Litter, Heat Cycle, Pedigree, Settings).
### 3.3 FRONTEND_GUIDE.md (UI/UX & React Patterns)
A guide focusing on the client-side implementation.
- **Context & Hooks**: Documentation of `useSettings`, `SettingsProvider`, and any other shared state mechanisms.
- **Component Patterns**: Key reusable components (`DogForm`, `PedigreeTree`, etc.).
- **Styling**: Use of CSS custom properties (theming) and global styles.
- **Pedigree Visualization**: How `react-d3-tree` is integrated and used for genealogy mapping.
- **Routing**: Client-side navigation structure using `react-router-dom`.
## 4. Non-Functional Requirements
- **Consistency**: Documentation must match the current state (v0.6.1) of the codebase.
- **Clarity**: Use clear, concise language and code examples where appropriate.
- **Maintainability**: Organize documents so they are easy to update when new features are added.
## 5. Success Criteria
- The three proposed documentation files (`DEVELOPMENT.md`, `API.md`, `FRONTEND_GUIDE.md`) are created in the project root.
- The documentation accurately reflects the current codebase architecture, API, and frontend patterns.
- An agent can use these documents to understand how to implement a new feature (e.g., adding a new field to the Dog model) without scanning the entire codebase.

89
.zenflow/tasks/init-9c68/spec.md Normal file
View File

@@ -0,0 +1,89 @@
# Technical Specification - Codebase Documentation (INIT)
This specification outlines the plan for creating comprehensive developer documentation for the Breedr codebase.
## Technical Context
- **Backend**: Node.js, Express, `better-sqlite3`.
- **Frontend**: React (Vite), `react-router-dom`, `axios`, `react-d3-tree`.
- **Database**: SQLite (managed via `server/db/init.js` and `server/db/migrations.js`).
- **Structure**: Monorepo-style with `client/` and `server/` directories.
## Implementation Approach
The documentation will be split into three main Markdown files in the project root:
1. **DEVELOPMENT.md**: Focuses on architecture, database design, and workflow.
2. **API.md**: Detailed documentation of all REST API endpoints.
3. **FRONTEND_GUIDE.md**: Focuses on React patterns, components, and styling.
### Research Methodology
- **Database**: Analyze `server/db/init.js` for table schemas and `parents` table logic.
- **API**: Scan `server/routes/*.js` for endpoints, middleware, and request/response structures.
- **Frontend**: Analyze `client/src/App.jsx` for routing, `client/src/hooks/` for state management, and `client/src/components/` for reusable patterns.
## Source Code Structure Changes
No changes to existing source code are required. Three new files will be created in the root directory:
- `/DEVELOPMENT.md`
- `/API.md`
- `/FRONTEND_GUIDE.md`
## Documentation Structure
### 1. DEVELOPMENT.md
- **Overview**: System purpose and high-level architecture.
- **Project Layout**: Description of key directories (`client`, `server`, `data`, `static`, `uploads`).
- **Database Design**:
- Explain the "Parents Table" approach (decoupling genealogy from the `dogs` table).
- Schema overview (Dogs, Litters, Health, Genetics, Settings).
- Initialization and migration process.
- **Getting Started**:
- `npm install` (root and client).
- `npm run dev` (concurrent execution).
- Database initialization (`npm run db:init`).
- **Coding Standards**: Backend route structure, async/await usage, error handling.
### 2. API.md
- **Base URL**: `/api`
- **Authentication**: (Note if any exists, currently seems open).
- **Endpoint Groups**:
- `Dogs`: CRUD operations, photo management, parent/offspring retrieval.
- `Litters`: Management of whelping records.
- `Health`: OFA records and test results.
- `Genetics`: DNA panel markers and results.
- `Breeding`: Breeding records and pairing simulations.
- `Settings`: Kennel profile management.
- **Data Models**: JSON schema examples for Dog, Litter, HealthRecord, etc.
### 3. FRONTEND_GUIDE.md
- **Tech Stack**: Vite, React, CSS Modules/Global CSS.
- **Routing**: `react-router-dom` configuration in `App.jsx`.
- **State Management**: `SettingsProvider` and `useSettings` hook.
- **Pedigree Engine**: Implementation of `react-d3-tree` and `pedigreeHelpers.js`.
- **Key Components**:
- `DogForm`: Complex form with parent selection.
- `PedigreeTree`: SVG-based genealogy visualization.
- `ClearanceSummaryCard`: Health status overview.
- **Styling**: Theming with CSS variables (found in `index.css` and `App.css`).
## Delivery Phases
### Phase 1: Core Architecture & Database (DEVELOPMENT.md)
- Document the tech stack and monorepo structure.
- Detail the SQLite schema and genealogy logic.
- Add setup and development commands.
### Phase 2: API Documentation (API.md)
- Document all routes in `server/routes/`.
- Provide request/response examples.
- Document the `parents` table integration in API responses.
### Phase 3: Frontend Guide (FRONTEND_GUIDE.md)
- Document React component patterns and hooks.
- Explain the pedigree visualization logic.
- Document routing and styling conventions.
## Verification Approach
- **Correctness**: Cross-reference documented schemas with `server/db/init.js`.
- **Accuracy**: Test documented API endpoints against the running server if possible, or verify via route handlers.
- **Completeness**: Ensure all components in `client/src/components` and routes in `server/routes` are mentioned or categorized.
- **Formatting**: Use `markdownlint` (if available) or manual review to ensure readability.