Public Access
104 lines
6.4 KiB
Markdown
104 lines
6.4 KiB
Markdown
# 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
|
|
- past change `proposal.md` and `design.md` if a new spec is in conflict with an old one.
|
|
|
|
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
|
|
|
|
Before restarting the local Meeting Assistant application, check whether a meeting is currently being recorded, transcribed, finalized, or summarized through the recording status endpoint and/or logs. Do not restart the application while an active meeting run is recording, transcribing, finalizing speaker recognition, waiting on OCR, or summarizing unless the user explicitly tells you to restart anyway.
|
|
|
|
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.
|
|
|
|
## Workflow Engine Documentation
|
|
|
|
When changing the meeting workflow engine, update `docs/meeting-workflow-engine.md` in the same change. This includes changes to:
|
|
|
|
- YAML rule shape or configuration
|
|
- supported triggers, states, conditions, expression variables, helper functions, or Razor template model
|
|
- supported steps or step semantics
|
|
- workflow event emission points in the recording lifecycle
|
|
- safety behavior for missing files, invalid rules, persistence, or local ignored rule files
|
|
|
|
Keep `README.md` as the short operational overview and keep `docs/meeting-workflow-engine.md` as the detailed reference.
|
|
|
|
Before finishing code changes, run the narrowest useful test command first. For broader changes, run:
|
|
|
|
```powershell
|
|
dotnet test MeetingAssistant.slnx
|
|
openspec validate <change-id> --strict
|
|
```
|