Skip to content

chore: add AGENTS.md, IDEAS.md, PENDINGS.md, CI workflow, and test infrastructure #1

Description

@teckedd-code2save

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

  • AGENTS.md exists at repo root: stack, directory map, run instructions, conventions (~80 lines)
  • IDEAS.md exists with 15-20 concrete ideas organized by domain
  • PENDINGS.md exists with 15-25 specific gotchas/constraints with severity notes
  • .github/workflows/ci.yml runs on push/PR to main and passes on main
  • At least 5 baseline pytest tests pass in CI

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions