Skip to content

Document agent-assisted spec contributions #511

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
riddim-developer-bot merged 2 commits into from
May 20, 2026
Merged

Document agent-assisted spec contributions #511

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7c45c96
Document agent-assisted spec contributions
May 20, 2026
2d9328e
Merge branch 'main' into docs/community-agent-intake
sunnypurewal May 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 65 additions & 18 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,14 @@
# Contributing to epac

Thanks for your interest in helping improve epac. We welcome clear bug reports, thoughtful suggestions, and well-scoped pull requests.
Thanks for your interest in helping improve epac. This repository is open source so you can inspect how the product works and use your own coding agent to help shape feature proposals.

epac's community contribution path is product-first. We are not currently using community source-code pull requests as the main way to add product features. Instead, we want each substantial contribution to become a well-formed spec that maintainers can review and, if accepted, route into the [Riddim Software](https://riddimsoftware.com/) Factory.

The public intake service and tracker are not live yet. Until they are, use this guide to prepare a proposal before opening a GitHub issue or contacting the maintainers.

## How to report an issue

Before opening a pull request, start by filing an issue with:
For a bug report, open an issue with:

- a short, descriptive title
- what you expected to happen
Expand All @@ -25,27 +29,70 @@ Attach the validated `SPEC.md` contents or rendered issue body to the issue.

If this is a question or clarification request, reach out via email at [sunny@riddimsoftware.com](mailto:sunny@riddimsoftware.com).

## How to propose a change
## How to propose a feature

Start by cloning the repo and opening it in your preferred coding agent. Ask the agent to read this file, `README.md`, `CLAUDE.md` or `AGENTS.md`, and the relevant product or architecture docs before drafting a proposal.

Your agent may edit the checkout locally to explore an idea or draft evidence for the spec. Those edits are scratch work. They are not the expected contribution artifact, and you do not need to run the app locally to contribute.

The expected artifact is one top-level spec. Depending on scope, that spec may describe:

- one issue for a narrow feature or bug fix
- one project with several child issues
- one initiative with multiple projects

Do not split one discussion into unrelated proposals. If your idea contains several independent outcomes, ask your agent to identify the single top-level shape or recommend splitting the discussion.

## Factory readiness checklist

A proposal is ready for maintainer review when it includes:

- **Use case** — who the feature is for, what they are trying to do, and what success looks like.
- **User value** — why this matters for epac users now.
- **Official data source** — the government or open-data source, owner, URL, format, update cadence, and required fields.
- **Data provenance** — how any app-visible claim traces back to the source.
- **App behavior** — what the user will see, do, receive, or configure in epac.
- **Acceptance criteria** — testable criteria, preferably written as `Given / When / Then`.
- **Out of scope** — related work that is intentionally not included.
- **Implementation surface** — likely affected areas such as `ios/`, `backend/`, `website/`, `data/`, `shared/`, or release metadata.
- **Verification plan** — commands, manual checks, screenshots, or a clear reason verification was not run.
- **Risks and edge cases** — privacy, stale data, missing data, civic neutrality, App Store review, or release concerns.

If the official data source is unclear, submit a source-discovery proposal instead of a product feature. A good source-discovery proposal explains the user need, candidate sources, and what must be proven before the feature can be built.

## Data source policy

epac is a civic app. Product features must be grounded in authoritative public sources.

- Prefer official government or open-data sources.
- Do not propose new Riddim-owned runtime backend dependencies for the app.
- Do not invent, summarize, or rewrite civic facts with generated text.
- Treat postal code, location, and notification data as sensitive. Explain why the data is needed and how the app can minimize retention or avoid server-side collection.
- If data is unavailable, stale, licensed restrictively, or not machine-readable, state that clearly in the proposal.

Examples of appropriate source categories include House of Commons open data, Elections Canada electoral geography, Statistics Canada public datasets, and other official Canadian public records.

## What about local edits?

Local edits are optional scratch work. They can help your agent answer questions like:

- Is this feasible in the current architecture?
- Which module would be affected?
- What source data shape does the app need?

1. Open an issue to discuss the change (especially for behavior changes or new features).
2. Link related issues and docs.
3. Keep the change focused and include rationale plus trade-offs.
4. Ask for feedback if you are unsure of scope.
Please do not open product-feature PRs with those local edits unless a maintainer explicitly asks for one. Maintainers own final implementation, review, release, and App Store submission.

## Branching and pull requests
## Pull requests

- Create a branch from `main`.
- Keep PRs small and scoped to one purpose.
- Include a clear title and summary of what changed and why.
- PRs may receive automated first-pass review; humans review and merge.
- Reference the issue(s) you are addressing and include test evidence in the PR description.
Small non-product fixes may still be appropriate as pull requests, such as documentation corrections, typo fixes, broken links, or test-only reproductions requested by a maintainer.

## Local development expectations
For any PR a maintainer asks you to open:

- iOS work: Xcode and the project toolchain required by `ios/README.md`/`README.md`.
- Backend work: Ruby/Go/Python tooling for your service plus any repository-specific dependencies (for example, `go test`, `swiftlint --strict`, or database/local pipeline prerequisites).
- Add/update tests where practical and run the relevant checks before opening a PR.
- Keep file and API changes small and easy to review.
- create a branch from `main`
- keep the PR small and scoped to one purpose
- include a clear title and summary of what changed and why
- reference the issue or proposal you are addressing
- include test evidence in the PR description

## Community behavior

Expand Down
140 changes: 32 additions & 108 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,128 +1,52 @@
# epac

**Canada's Parliament, in your pocket — an iPhone app for tracking MPs, bills, votes, debates, expenses, and lobbying activity from official Canadian government sources.**
epac is built through agent-assisted specs.

<p align="center">
<a href="https://epac.riddimsoftware.com/">
<img src="website/ss-1-light.png" alt="epac iPhone screenshot showing the app's parliamentary tracking interface" width="320">
</a>
</p>
The canonical way to contribute is not to set up the app locally, pick a programming language, or send a feature patch. Clone the repo, open it in your coding agent, and use the repository context to turn an idea into a `SPEC.md`.

<p align="center">
<a href="https://apps.apple.com/ca/app/epac/id1224459142">
<img src="website/app-store.svg" alt="Download on the App Store" height="52">
</a>
</p>
The spec is the contribution. The [Riddim Software](https://riddimsoftware.com/) Factory takes over from there: it reviews accepted specs, turns them into implementation work, produces something testable, iterates when needed, and can ship the result to TestFlight and the App Store.

<p align="center">
<a href="https://epac.riddimsoftware.com/">Homepage</a>
·
<a href="https://apps.apple.com/ca/app/epac/id1224459142">App Store</a>
</p>
## How It Works

## What it does and why
1. Clone this repository.
2. Open the repo in your preferred coding agent.
3. Discuss the feature, bug, or release improvement with the agent.
4. Let the agent read the repo context and shape the proposal.
5. Open a spec-only pull request that adds:

`epac` turns the House of Commons record into something more readable than a feed of PDFs, XML, and committee pages. The app lets Canadians follow what MPs actually do between elections: how they vote, what bills they sponsor, what gets said in debate, and which topics are active in Parliament.

One of its core ideas is **Hansard as chat**. Instead of treating parliamentary debate as a wall of transcript text, epac presents speeches in a conversational format that is faster to scan on a phone while still staying grounded in the official record. The goal is not commentary or partisanship; it is a civic tool that makes primary-source parliamentary data easier to browse, search, and verify.

## Architecture

This repository is intentionally polyglot because each part of the product does a different job:

- **SwiftUI + SwiftData (`ios/`)** — the iPhone app, widgets, app clip, local persistence, and product UI.
- **Go services (`backend/`)** — API endpoints, ingestion workers, and backend jobs that fetch, normalize, and serve parliamentary data.
- **Python tools (`backend/` and `scripts/`)** — focused ingestion utilities, release helpers, localization checks, and marketing tooling.
- **HTML/CSS/JS (`website/`)** — the public website, landing pages, topic pages, and App Store support web surfaces.
- **Data snapshots (`data/` and bundled app assets)** — source-derived files that help feed the app experience.

Together, those layers support the same product loop: gather authoritative public data, structure it, and deliver it in a mobile experience that makes Parliament easier to follow.

## Build and run

### iOS app

Requirements:

- Xcode with iOS 17+ simulator support
- macOS

Open the project in Xcode:

```bash
open ios/epac.xcodeproj
```

Then select the `epac` scheme and run it in the simulator.

Alternatively, build from the command line using the provided `ios/Makefile`. This path is recommended for first-time contributors as it automatically finds an available simulator.

First, install [xcbeautify](https://github.com/cpisciotta/xcbeautify):

```bash
brew install xcbeautify
```text
proposals/<short-slug>/SPEC.md
```

Then build and run:
The PR should not include product-code changes unless a maintainer explicitly asks for them. Local edits are fine as scratch work while your agent explores the idea, but they are evidence for the spec, not the artifact we review.

```bash
cd ios
make build # Build the app
make simulator # Build and deploy to an available simulator
```

`make simulator` automatically targets an available iPhone simulator. To target a specific one, you can override `SIM_NAME`:

```bash
cd ios && make simulator SIM_NAME='iPhone 16'
```

If you prefer to use `xcodebuild` directly, you can list available simulators with `xcrun simctl list devices available` and then specify one:

```bash
cd ios
xcodebuild -project epac.xcodeproj -scheme epac -destination 'platform=iOS Simulator,name=YOUR_SIMULATOR_NAME' build
```

### Backend and tooling prerequisites
## What Goes In The Spec

Requirements:
A useful `SPEC.md` is a short design document. It should explain:

- Go 1.24+
- Python 3
- the problem
- the goals and non-goals
- the user jobs or use cases
- the official government or open-data sources involved
- how app-visible claims trace back to those sources
- the proposed product behavior
- privacy, safety, and civic-neutrality risks
- validation evidence from the discussion or local exploration
- open questions and alternatives considered
- whether the work looks like one issue, a project, or an initiative

Install the repo's Python dev dependency:
The most important epac rule: product behavior must be grounded in authoritative public sources. If the data source is unclear, write a source-discovery spec instead of a feature spec.

```bash
pip install -r requirements-dev.txt
```

Useful local checks:

```bash
cd backend/search && go test ./...
cd backend/hansard-backfill && go test ./...
python3 backend/cabinet/cabinet_ingest.py --dry-run
```
## What Happens Next

The iOS app is the main product surface; the backend services and scripts exist to ingest, shape, and publish the public parliamentary data that the app depends on.
Maintainers review the spec PR. If the spec needs more detail, the reviewer asks for changes and you can continue the discussion with your coding agent. If the spec is accepted, it can be routed into the Riddim Software Factory.

## Contribute

Issues and pull requests are welcome. Start with [CONTRIBUTING](CONTRIBUTING.md), then read the [Code of Conduct](CODE_OF_CONDUCT.md) and [Security Policy](SECURITY.md).

Bug fixes can be prepared with the repo-local intake harness:

```bash
python3 scripts/intake/bugfix_spec.py new
```
The factory does a strong job of implementation, but software still needs feedback. Some specs produce a testable result on the first pass. Some need an iteration after testing. The contribution loop is designed for that: spec, implement, test, refine, release.

This creates a validated `SPEC.md` that captures the observed behavior, expected
behavior, evidence plan, and reporter validation path before implementation
starts. See [docs/factory/bugfix-intake.md](docs/factory/bugfix-intake.md).
Future intake service work may add a tracker that follows an accepted spec into Linear, implementation, PR review, TestFlight, and App Store release. For now, the spec PR is the source of truth.

PRs may receive an automated first-pass review; humans review and merge.
## Repo Context

## License
This repo contains the source, data tooling, release scripts, and agent-readable project context that a coding agent needs to reason about epac. You do not need to run the app locally to contribute a spec.

Distributed under the [MIT License](LICENSE).
For the current contribution rules, read [CONTRIBUTING.md](CONTRIBUTING.md).
Loading