Summary
adwuma-pa (Edward's AI family care network for Ghanaian elders, built for the Build Small Hackathon) is a hybrid Python + JS repo with a solid README, LICENSE, and rich build documentation (ADWUMA_PA_SPEC_V2.md, CODEX_BUILD_LOG.md, FIELD_NOTES.md, MODAL_RUNBOOK.md, SUBMISSION.md) — but it has zero agent-facing docs and zero automation: no AGENTS.md, IDEAS.md, PENDINGS.md, CI workflow, or tests.
What to do
1. AGENTS.md
Create a contributor/agent guide (~80 lines) covering:
- Tech stack: Python (FastAPI/Modal backend in
modal_backend/, app.py), JS/React (package.json), Twi ASR finetuning (finetune/)
- Directory map:
modal_backend/, services/, scheduler/, finetune/, db/, config/, scripts/, spaces/, docs/
- How to run locally (Python + Node), key scripts, deployment via Modal (
MODAL_RUNBOOK.md reference)
- Code conventions — match the README's tone
2. IDEAS.md
Create a forward-looking roadmap with 15-20 concrete ideas organized by domain (voice-first features for elders, Twi ASR integration building on the existing finetune work, care-network features, deployment improvements). Match the format used in e.g. convoy/IDEAS.md or groundcontrol/IDEAS.md.
3. PENDINGS.md
Document known sharp edges and gotchas (15-25 items) sourced from MODAL_RUNBOOK.md, CODEX_BUILD_LOG.md, FIELD_NOTES.md, and HACKATHON_TODO.md — e.g. Modal cold-start constraints, scheduler/service coupling, Twi ASR finetuning data gotchas, hackathon-time shortcuts that need revisiting.
4. CI workflow
Add .github/workflows/ci.yml:
- Python job:
ruff check + pytest (with PYTHONPATH: ${{ github.workspace }} on the test step)
- JS job:
npm ci + build/typecheck (if the JS side has a build script)
- Trigger on push to
main and PRs to main
5. Test infrastructure
Add baseline pytest tests for core Python modules (app.py, modal_backend/, services/). The repo currently has zero test files (verified via git tree).
Why this matters
- AGENTS.md lets future agent runs (and Edward) operate on this repo safely without re-reading the entire build log
- IDEAS.md turns the hackathon project into a maintainable portfolio piece with a clear roadmap
- PENDINGS.md captures hard-won constraints currently scattered across FIELD_NOTES / CODEX_BUILD_LOG before they're lost
- CI makes regressions visible and is expected for any repo shown to clients or recruiters
- Tests protect the Modal backend and scheduler logic from silent breakage as the project evolves past the hackathon
Acceptance criteria
Summary
adwuma-pa(Edward's AI family care network for Ghanaian elders, built for the Build Small Hackathon) is a hybrid Python + JS repo with a solid README, LICENSE, and rich build documentation (ADWUMA_PA_SPEC_V2.md,CODEX_BUILD_LOG.md,FIELD_NOTES.md,MODAL_RUNBOOK.md,SUBMISSION.md) — but it has zero agent-facing docs and zero automation: no AGENTS.md, IDEAS.md, PENDINGS.md, CI workflow, or tests.What to do
1. AGENTS.md
Create a contributor/agent guide (~80 lines) covering:
modal_backend/,app.py), JS/React (package.json), Twi ASR finetuning (finetune/)modal_backend/,services/,scheduler/,finetune/,db/,config/,scripts/,spaces/,docs/MODAL_RUNBOOK.mdreference)2. IDEAS.md
Create a forward-looking roadmap with 15-20 concrete ideas organized by domain (voice-first features for elders, Twi ASR integration building on the existing finetune work, care-network features, deployment improvements). Match the format used in e.g.
convoy/IDEAS.mdorgroundcontrol/IDEAS.md.3. PENDINGS.md
Document known sharp edges and gotchas (15-25 items) sourced from
MODAL_RUNBOOK.md,CODEX_BUILD_LOG.md,FIELD_NOTES.md, andHACKATHON_TODO.md— e.g. Modal cold-start constraints, scheduler/service coupling, Twi ASR finetuning data gotchas, hackathon-time shortcuts that need revisiting.4. CI workflow
Add
.github/workflows/ci.yml:ruff check+pytest(withPYTHONPATH: ${{ github.workspace }}on the test step)npm ci+ build/typecheck (if the JS side has a build script)mainand PRs tomain5. Test infrastructure
Add baseline
pytesttests for core Python modules (app.py,modal_backend/,services/). The repo currently has zero test files (verified via git tree).Why this matters
Acceptance criteria
AGENTS.mdexists at repo root: stack, directory map, run instructions, conventions (~80 lines)IDEAS.mdexists with 15-20 concrete ideas organized by domainPENDINGS.mdexists with 15-25 specific gotchas/constraints with severity notes.github/workflows/ci.ymlruns on push/PR to main and passes on main