From d4d515eabae22606722091ff431f0fa0ee6eeb0b Mon Sep 17 00:00:00 2001 From: Eddie Soehnel Date: Tue, 17 Mar 2026 08:39:34 -0600 Subject: [PATCH] v 1.1.0 ## 1.1.0 - 2026-03-16 ### Added Significant more structure to overall repo with more folders, rules for how to do things from https://jamon.dev/night-shift, changes docs to specs, added tasks folder. --- PRODUCT-DEV-OS.md | 142 ++++++++++++------ PROJECTRULES.md | 7 - PROJECTRULESPROCESSES.md | 39 +++++ docs/agents.md | 14 -- docs/build-plan.md | 1 - docs/decisions.md | 1 - .../1_strategy_s}/vision-strategy.md | 0 {docs => specs/2_systems_s}/api-spec.md | 0 {docs => specs/2_systems_s}/architecture.md | 0 {docs => specs/2_systems_s}/data-model.md | 0 {docs => specs/2_systems_s}/environments.md | 0 {docs => specs/2_systems_s}/system.md | 0 .../3_product_development_s}/user-flows.md | 0 specs/agents.md | 23 +++ specs/build-plan.md | 1 + specs/decisions.md | 1 + specs/personas.md | 19 +++ 17 files changed, 183 insertions(+), 65 deletions(-) delete mode 100644 PROJECTRULES.md create mode 100644 PROJECTRULESPROCESSES.md delete mode 100644 docs/agents.md delete mode 100644 docs/build-plan.md delete mode 100644 docs/decisions.md rename {docs => specs/1_strategy_s}/vision-strategy.md (100%) rename {docs => specs/2_systems_s}/api-spec.md (100%) rename {docs => specs/2_systems_s}/architecture.md (100%) rename {docs => specs/2_systems_s}/data-model.md (100%) rename {docs => specs/2_systems_s}/environments.md (100%) rename {docs => specs/2_systems_s}/system.md (100%) rename {docs => specs/3_product_development_s}/user-flows.md (100%) create mode 100644 specs/agents.md create mode 100644 specs/build-plan.md create mode 100644 specs/decisions.md create mode 100644 specs/personas.md diff --git a/PRODUCT-DEV-OS.md b/PRODUCT-DEV-OS.md index 7634662..a06ea89 100644 --- a/PRODUCT-DEV-OS.md +++ b/PRODUCT-DEV-OS.md @@ -18,9 +18,9 @@ The most valuable stack is: ### 3-layer system -1. Knowledge layer → what the system is supposed to do. The truth via highly structured executable knowledge that AI can understand -2. Product layer → takes the knowledge layer and executes it: develop code, develop the product, produce the product -3. Data layer → what the system observes, stores, and learns from based on production. The data validates reality, that leads to iterate above to improve +1. Knowledge layer (specs/) → what the system is supposed to do. The truth via highly structured executable knowledge that AI can understand. +2. Product layer (srv/) → takes the knowledge layer and executes it: develop code, develop the product, produce the product. +3. Data layer (data/) → what the system observes, stores, and learns from based on production. The data validates reality, that leads to iterate above to improve. ### Structure For Git Repo @@ -34,57 +34,115 @@ The most valuable stack is: ### repo/ -README.md \ see template -CHANGELOG.md -VERSION.md \ see template -PROJECTRULES.md \ see template +- README.md \ high level overview of project +- CHANGELOG.md \ +- VERSION.md \ +- PROJECTRULESPROCESSES.md \ agent and human rules/processes -### docs/ -*The executable structure layer: product intent, product behavior, systems design, build plan* -agents.md \ how this repo works, what the structure means, rules for editing code. AI should modify docs before modifying code. All new features must update data-model.md. All tests must pass before merge. -vision/concept validation/strategy/mission/goals/marketing/sales/distribution/goals/target customer/constraints/success metrics/.md \ use the **B2C framework**. -requirements/desired outcomes.md -user-flows/screen states/actions.md -architecture.md \- infrastructure, platforms, code bases, tech stack, engineering design, environment \ the [long-term tech stack is here](https://docs.google.com/document/d/1BtcV4Lpv4E8vf5jMHcYmzw__U8ZN0ZCx0-1KTo0Z-1U/edit?tab=t.0) -environments.md - multiple environments that exist - dev, staging, production -data-model.md \- how the data flows through the product, where it ends up, how it is , structure, relationships, rules governing it, where stored -api-spec.md \- AI capabilities, focus for this project. -build-plan.md \- sequences, tasks, modules, dependencies, components -decisions.md \ why we did what we did, why we chose A over B, etc. Architecture Decision Records (ADR). provide context, decision, risks, consequences. Document using the [decision layer and biases layer](https://docs.google.com/document/d/1VjtP-jPn-wOpE8z5QSVOdk-pPxneyuDDM6z_a9OIpYY/edit?tab=t.0) -system.md \ map of how the knowledge layer connects to the code, how data flows, how AI should reason about the repo +### specs/ + +*The executable structure layer, organized by main function and in order* + +- agents.md \ Functionas more like a router, telling AI where to find stuff. And general rules. +- build-plan.md \- sequences, tasks, modules, dependencies, components +- decisions.md \ why we did what we did, why we chose A over B, etc. Architecture Decision Records (ADR). provide context, decision, risks, consequences. Document using the [decision layer and biases layer](https://docs.google.com/document/d/1VjtP-jPn-wOpE8z5QSVOdk-pPxneyuDDM6z_a9OIpYY/edit?tab=t.0) +- personas.md \ As AI may run sub-agents, this document defines the personas for those sub-agents. + +#### 1_strategy_s + +- vision/concept validation/strategy/mission/goals/marketing/sales/distribution/goals/target customer/constraints/success metrics/.md \ use the **B2C framework**. + +#### 2_systems_s + +- api-spec.md \- AI capabilities, focus for this project. +- architecture.md \- infrastructure, platforms, code bases, tech stack, engineering design, environment \ the [long-term tech stack is here](https://docs.google.com/document/d/1BtcV4Lpv4E8vf5jMHcYmzw__U8ZN0ZCx0-1KTo0Z-1U/edit?tab=t.0) +- data-model.md \- how the data flows through the product, where it ends up, how it is , structure, relationships, rules governing it, where stored +- environments.md - multiple environments that exist - dev, staging, production +- system.md \ map of how the knowledge layer connects to the code, how data flows, how AI should reason about the repo + +#### 3_product_development_s + +- user-flows/screen states/actions.md + +#### 4_finance_s + +#### 5_production_logistics_s + +#### 6_marketing_s + +#### 7_sales-distribution_s + +#### 8_support_s + +### tasks + +*Task items by document with dates* ### srv/ + *The production/execution layer for AI to execute on. Code is created in files. Code is well documented and explains why the code exists, what it does, maintenance tips, gotchas if any.* -app/ -models/ -scripts/ -services/ -ui/ -utils/ -routes/ + +#### digital + +*digital/software-based products/services* + +- app/ +- models/ +- scripts/ +- services/ +- ui/ +- utils/ +- routes/ + +#### physical + +*physical-based products/services* ### data/ + *Data that is already a part of the system (ie.: CRM customer data) or which gets produced from the system. repo/ topline and docs/ are strategy, systems and product development are src/, data is all other functions, pulled from **B2C Framework** -json-db/ -schemas/ -runtime-exports/ -finance/ -marketing/ -sales/ -support/ + +#### 1_strategy_d + + +#### 2_systems_d + +- json-db/ +- schemas/ +- runtime-exports/ + +#### 3_product_development_d + + +#### 4_finance_d + + +#### 5_production-logistics_d + + +#### 6_marketing_d + + +#### 7_sales-distribution_d + + +#### 8_support_d ### tests/ + *Run time feedback* -acceptance-tests.md -qa-checklists.md -dev-tests/ +- acceptance-tests.md \ +- qa-checklists.md \ +- dev-tests/ ### ops/ -deployment.md -monitoring.md -maintenance.md -backup.md -security.md + +- deployment.md \ +- monitoring.md \ +- maintenance.md \ +- backup.md \ +- security.md \ ### config/ + .env files, API's, feature flags, for both dev and production diff --git a/PROJECTRULES.md b/PROJECTRULES.md deleted file mode 100644 index 3c38fae..0000000 --- a/PROJECTRULES.md +++ /dev/null @@ -1,7 +0,0 @@ -# Project Rules - -1. Never modify production database schemas without migration scripts. -2. Update documentation when architecture changes. -3. Follow directory structure strictly. -4. Do not place business logic in API controllers. -5. All new features require tests. diff --git a/PROJECTRULESPROCESSES.md b/PROJECTRULESPROCESSES.md new file mode 100644 index 0000000..be77dd1 --- /dev/null +++ b/PROJECTRULESPROCESSES.md @@ -0,0 +1,39 @@ +# Project Rules + +1. Never modify production database schemas without migration scripts. +2. Update documentation when architecture changes. +3. Follow directory structure strictly. +4. Do not place business logic in API controllers. +5. All new features require tests. + +# AI Processes + +0. Prep: Cleans the working tree by analyzing any uncommitted work and doing the right thing with it (stash or commit). Also runs the entire current test suite and fixes any failures it encounters. +1. Picks a task from bugs first, or if bugs are complete, a feature that I've completed a spec for +2. Loads up the spec, and then analyzes it +3. Loads relevant docs, then looks at relevant code +4. Develops a testing plan (absolutely critical) +5. Writes extensive tests for this, then runs them, expecting failures +6. Develops an extensive plan of its own (I NEVER read this, I do not care) +7. Runs sub-agents as critical reviewers (review agents) based on 6 personas I've detailed in REVIEW_PERSONAS.md: Designer, Architect, Domain Expert, Code Expert, Performance Expert, Human Advocate. Each of these "owns" a portion of the docs, and reviews against their own documentation, including suggesting where their own docs need to be adapted. +8. Adapts plan based on review agent reviews, and loops to 7 until green light from all review agents +9. Implements the plan, including documentation adjustments (docs live in the same code base under Docs) +10. Runs type checking, linting, compiler, other static analysis tools such as bundle size reporter, as many things as possible, and of course the relevant tests themselves, and verifies that it works, iterating as it goes. Be as strict as possible with your type checking and linting system. I used to be anti strictness, but that was when I was a wetware dev. For agents, I want the most strictness possible. +11. Run the entire test suite to protect against regressions, fix any new issues +12. Runs the review agents again on the implementation diff, and loops back to step 10 until getting a green light from all review agents. +13. Add any encountered unrelated TODOs for human review that they've noticed along the way to the TODO doc +14. Wrap-up: write a CHANGELOG entry, commit with a detailed commit message meant for human context when reviewing the code. (More on commits later) +15. Loop back to the beginning (step 1), and select the next task or spec. +16. When completely done, write up a report for human review. Extremely concise. Details live in commit messages. + +# Human Processe After AI Processes + +1. Review: Check the changelog and agent recap. Then go commit by commit, reviewing each commit message, implementation diff, tests, and docs changes. +2. Stacked commits: I keep all commits in the same branch so they stack on each other (a good use for stacked PRs, btw). Improvements carry forward to each subsequent commit. Fewer conflicts, better results, less duplicative work. +3. Quick fixes: If I need to correct something quickly, I do it using an interactive agent session or by hand. But before I do, I ALWAYS analyze and correct the docs, workflow, and validations/testing first. +4. Postmortem: If the agent misbehaved, don't just fix the code. Don't tell it to fix the code either. Use that valuable context to figure out why it did the wrong thing. Have it analyze its own context and tell you what docs, skills, or workflow led it astray, and what improvements would make it make the right decision next time. Have it fix those issues first — be diligent, because you can amortize the improvement over the rest of your project. Only after that, have it fix the original issue. Use that feedback cycle and continuous improvement to get to a point where it is making the right decisions more often than not. +5. Manual testing: I check almost every change manually and thoroughly. Not just to catch bugs, but to catch gaps in my docs, skills, specs, validations/tests, and my own understanding of the system. And fix them! +6. Spec writing: Then I get back to the first part — gathering requirements, writing specs, doing architecture, and thinking a lot. + +# Notes +Automated testing is incredibly important. This WILL NOT WORK if you don't have a super robust end-to-end testing harness in place and excellent docs so the agents can create their own tests. diff --git a/docs/agents.md b/docs/agents.md deleted file mode 100644 index c4f2d1b..0000000 --- a/docs/agents.md +++ /dev/null @@ -1,14 +0,0 @@ - -# Context -To understand the general process for this repo, please review the PRODUCT-DEV-OS.md file. - -# This Repo - -how this repo works -what the structure means -rules for editing code - - -# Additional General Requirements - - Code is created in files. Code is well documented and explains why the code exists, what it does, maintenance tips, gotchas if any. diff --git a/docs/build-plan.md b/docs/build-plan.md deleted file mode 100644 index 0a1a961..0000000 --- a/docs/build-plan.md +++ /dev/null @@ -1 +0,0 @@ -api-spec.md \ No newline at end of file diff --git a/docs/decisions.md b/docs/decisions.md deleted file mode 100644 index 0a1a961..0000000 --- a/docs/decisions.md +++ /dev/null @@ -1 +0,0 @@ -api-spec.md \ No newline at end of file diff --git a/docs/vision-strategy.md b/specs/1_strategy_s/vision-strategy.md similarity index 100% rename from docs/vision-strategy.md rename to specs/1_strategy_s/vision-strategy.md diff --git a/docs/api-spec.md b/specs/2_systems_s/api-spec.md similarity index 100% rename from docs/api-spec.md rename to specs/2_systems_s/api-spec.md diff --git a/docs/architecture.md b/specs/2_systems_s/architecture.md similarity index 100% rename from docs/architecture.md rename to specs/2_systems_s/architecture.md diff --git a/docs/data-model.md b/specs/2_systems_s/data-model.md similarity index 100% rename from docs/data-model.md rename to specs/2_systems_s/data-model.md diff --git a/docs/environments.md b/specs/2_systems_s/environments.md similarity index 100% rename from docs/environments.md rename to specs/2_systems_s/environments.md diff --git a/docs/system.md b/specs/2_systems_s/system.md similarity index 100% rename from docs/system.md rename to specs/2_systems_s/system.md diff --git a/docs/user-flows.md b/specs/3_product_development_s/user-flows.md similarity index 100% rename from docs/user-flows.md rename to specs/3_product_development_s/user-flows.md diff --git a/specs/agents.md b/specs/agents.md new file mode 100644 index 0000000..4fb5264 --- /dev/null +++ b/specs/agents.md @@ -0,0 +1,23 @@ + +# Context + +To understand the general process for this repo, please review the PRODUCT-DEV-OS.md file. + +# This Document + +Functionas more like a router, telling AI where to find stuff. + +# This Repo + +- Rules for editing code +- AI should modify docs before modifying code. +- All new features must update data-model.md. All tests must pass before merge. + +# Where To Find Documentation + +in specs folder. Ignore anything with "draft" in the name. Pointy out workflow docs, skill docs (or agent skills) and system documentation (describing different parts of the system) + + +# Additional General Requirements + + Code is created in files. Code is well documented and explains why the code exists, what it does, maintenance tips, gotchas if any. diff --git a/specs/build-plan.md b/specs/build-plan.md new file mode 100644 index 0000000..9a35375 --- /dev/null +++ b/specs/build-plan.md @@ -0,0 +1 @@ +sequences, tasks, modules, dependencies, components diff --git a/specs/decisions.md b/specs/decisions.md new file mode 100644 index 0000000..2f4881d --- /dev/null +++ b/specs/decisions.md @@ -0,0 +1 @@ +decision.md diff --git a/specs/personas.md b/specs/personas.md new file mode 100644 index 0000000..add32a0 --- /dev/null +++ b/specs/personas.md @@ -0,0 +1,19 @@ +# Description + +As AI may run sub-agents, this document defines the personas for those sub-agents. + +# Sub-Agent Personas + +Each of these "owns" a portion of the docs, and reviews against their own documentation, including suggesting where their own docs need to be adapted. + +## Designer + +## Architect + +## Domain Expert + +## Code Expert + +## Performance Expert + +## Human Advocate