Shared Goals Instance

Shared Goals platform instance: FastAPI backend, SQLite persistence, read-only web UI later, and JSON REST API for agents.

The PRD source of truth lives in shared-goals/prd. Start implementation from the acceptance scenarios and backend contract there.

Development

Use the Makefile targets for the local development flow:

make acceptance
make lint
make test
make check

Shared Goals environments are selected with SG:

make run                # SG=prod by default, runs the instance on the prod port
SG=prod make run        # explicit prod run on the current machine
SG=dev make run         # dev run on 0.0.0.0:8016

Service lifecycle targets are prod-only:

make install-service
make start
make restart
make stop

make install-service installs the system service unit and a sudoers rule for passwordless service operations on that unit. After that, make start, make stop, and make restart use sudo -n for the service commands.

The instance repo Makefile is prod-first, and make run uses only server bind settings. On SG=dev, the server enables the seed endpoint and points it at the repo seed.json. Trigger seeding from your client-side workflow with SG=dev.

Authentication is KISS for MVP: agent keys live in the database and point to a user. The dev bootstrap path creates a default development user and agent key record automatically, so local development flows work without extra setup.

For a focused TDD loop, pass a specific file or test:

make test TEST=tests/acceptance/test_agent_goal_flow.py

Run the local API:

make run

TDD flow: write or update the HTTP acceptance test first, run the focused target and see it fail, implement the smallest behavior, rerun the same target, then run make check before committing. Use make format for mechanical Python formatting.

MVP Scope

The first implementation slice supports agent-facing goal creation and simple catalog search under /api/v1. Additional behavior should land through HTTP-level acceptance tests first.