meeting-assistant/AGENTS.md

Repository Instructions

Project Orientation

Meeting Assistant is a spec-driven .NET service for capturing, transcribing, summarizing, and enriching meetings without depending on a specific meeting platform API. When starting work in this repository, read README.md first for the current runtime architecture, then read the OpenSpec documents so you understand the current scope and capabilities before changing code:

• README.md
• openspec/config.yaml
• all specs under openspec/specs
• all active change specs under openspec/changes/*/specs
• active change proposal.md, design.md, and tasks.md only when more context is needed

Do not treat implementation code as the only source of truth. Requirements belong in OpenSpec changes.

Start Work Checklist

Before editing specs or code, do the following:

1. Run git status --short and note existing user or agent changes.
2. Identify whether there is an active OpenSpec change relevant to the request.
3. Read the relevant specs before reading implementation details.
4. Decide whether the request belongs to an existing change or needs a new change.
5. State that decision and the reason before editing requirements or code.

Development Cycle

Use the $tdd skill for feature work and bug fixes. Work in small vertical slices:

1. Add or update the relevant OpenSpec requirement/scenario.
2. Add one failing behavior test through the public interface.
3. Implement the minimum code needed to pass that test.
4. Repeat for the next behavior.
5. Refactor only after tests are green.
6. Run the relevant tests and openspec validate <change-id> --strict.

Tests should describe observable behavior and avoid coupling to implementation details.

For feature/spec work, keep the active OpenSpec tasks.md current enough that another agent can resume the work. Add or update task entries for meaningful behavior changes, but skip task churn for tiny documentation, config, or mechanical maintenance edits.

OpenSpec Change Policy

If the user explicitly asks to create a new change, create one.

If the user does not explicitly say whether to create a new change, decide from context:

• If an open change is already being worked in the current session and the user's request concerns that same behavior, treat it as part of that change.
• If there is no open change, create a new OpenSpec change for behavior or requirement changes unless the request is very small or not a spec change.
• Documentation-only edits, deployment variable fixes, build plumbing, and similarly narrow maintenance work usually do not need a new spec change.
• Bug fixes should still start with a failing test. The required behavior should be added as an addendum to the original spec/change that defined the intended behavior, rather than as an unrelated new requirement.

When in doubt, make the reasoning explicit before editing specs or code.

Change Completion

A spec/change is not considered done merely because code is merged, tests pass, or openspec validate succeeds. A change is ready to be accepted or archived only after the agent has verified the intended behavior through the most direct operational surface available.

Before archiving any OpenSpec change, perform a refactoring pass over the code and specs touched by that change. The pass must inspect both the current diff and the surrounding implementation context, because a small diff may reveal repeated patterns or structural problems that only become obvious when compared with nearby code.

Do the refactoring pass in these distinct areas, first start a subagent for each area to identify potential improvements in parallel, then implement them:

1. Check for DRYness. Look for duplication introduced by the change and for existing nearby duplication that the change now makes worth consolidating. A change may be small on its own, but if it is the fifth copy of the same idea, it is a refactoring target.
2. Check for SOLID violations. Look for responsibilities that are mixed together, abstractions that are hard to replace or test, interface shapes that force unrelated dependencies, and code paths that require modifying stable code for each new variant.
3. Check whether the implementation can be made simpler under KISS. Remove accidental abstractions, reduce branching, clarify names, and prefer the smallest structure that still supports the tested behavior and current spec.

Preserve behavior during this pass and run the relevant tests again afterward.

For Meeting Assistant, prefer verification through:

• local application endpoints
• generated or updated meeting note files
• transcription and summarization behavior tests
• application logs proving the end-to-end flow

If production or end-to-end verification is not possible, state exactly why and what lower-level verification was performed instead.

Implementation Notes

Keep source and deployment ownership separate:

• Manuel/meeting-assistant owns application source, tests, build configuration, container image publishing, and OpenSpec source changes.
• A future deployment repository, if created, should own Docker Compose, Traefik labels, secrets/variables, networks, and live image tag selection.

Before finishing code changes, run the narrowest useful test command first. For broader changes, run:

dotnet test MeetingAssistant.slnx
openspec validate <change-id> --strict