gistfile1.txt

Don't write code without explicit permission, focus on plans first.

# Development Process Overview
The files will be written to /project. For each of these pretend to be a different "person" so that you do not discuss implementation details at the product or design layer. Go step by step and work on each doc only after I've given the go ahead.

```
/project
/project/workstream.md
/project/design.md
/project/architecture.md
```

1. Product Management
    1. captured in workstream.md
    1. this file give us the zoomed out view of the project from a product management perspective
    1. a series of decisons about what to do with the product
    1. each entry is a "task" in the overall workstream
    1. each task has, goals, requirements, acceptance criteria
        1. clarify goal in 1-3 sentences and make sure it fits with the "workstream.md" file that outlines past features, current feature scope, and next steps
        1. clarify any requirements
        1. if applicable, recap the existing system interfaces
    1. it is updated as we progress through the project
    1. it is used to track progress and ensure that we are on track 
1. Design Proposal
    1. captured in design.md as uncomitted changes for the user interaction
    1. Organized by user workflow can be IPC, API, GUI, or CLI, whatever the consumer is of a given feature
    1. Outline the updated workflow -- use Jacob's law!
    1. Discuss any key interactions
1. Architecture Proposal
    1. capture in architecture.md propose the system changes features, enhancements, bug fixes that will fulfill the design
    1. contract using inputs and outputs at the API/user interface (highest level of abstraction) -- this will either be IPC calls, GUI interactions, CLI commands, or HTTP requests
    1. discuss a few high level examples
    1. have the file layout / directory structure in here
    1. At this point you should have a clear idea of what the new feature will do and how it will interact with the existing system
    1. Make sure to propose key packages and tech stack changes!l
1. Implementation Plan
    1. propose the implementation of the architecture captured as tests or other verifables -- these should be literal stubs in [workspace]/tests
    1. outline the core changes to message passing between components and any new components that need to be added
    1. can be one or more of:
        1. test_api.py
        1. test_system_effects.py -- side effects that other systems or services may use like sending external web requests or saving data
        1. test_cli.py 
        1. test_gui.py -- GUI interactions be it web or local Qt or what have you
1. During implementation focus on one testcase at a time with red-green-refactor, keeping changes small and focused. If we feel we need to adjust something at a higher level, STOP and let's discuss at that level then proceed again from there down this process

# Workspace
```
[workspace]
/project/...
/tests/... # user or system level tests (CLI, GUI, API, etc.)
/src/... # internal code including unit tests for each component as needed
./ # files for the workspace, .gitignore, .codeium, etc.
```

Testing components inside the project are colocated with the internal piece of code.

# For Python Workspaces:
1. always check for a uv.lock file and use `uv run python`
1. have a separate tests directory that is used to test the app or service as a black box, it should focus on "user" interfaces and how the app is consumed from the outside
1. always take a look at the pyproject.toml