Project Workflow

Essential Commands

Daily Development

make install
make test
make lint
make typecheck

Before Committing

make format
make lint
make typecheck
make test

Build And Release

make build-onefile
make build-onefile-container
dist/coffee --help
dist/coffee upgrade --help
docker run --rm cymbal-coffee:latest upgrade --help
readelf -Ws dist/coffee | rg -o 'GLIBC_[0-9.]+' | sort -Vu | tail

Guiding Principles

Beads backend is the Source of Truth: Use official Beads (bd) for task state. Do not run bd sync; that command does not exist. When markdown views need refresh, use the Flow plugin sync workflow if available, or reconcile .agents/specs/ and .agents/flows.md from Beads state explicitly.
The Tech Stack is Deliberate: Changes to the tech stack must be documented in tech-stack.md before implementation
Test-Driven Development: Write unit tests before implementing functionality
High Code Coverage: Aim for >80% code coverage for all modules
User Experience First: Every decision should prioritize user experience
Non-Interactive & CI-Aware: Prefer non-interactive commands. Use CI=true for watch-mode tools (tests, linters) to ensure single execution.
Use the Repo's Real Commands: Prefer canonical project entrypoints such as make lint, make test, make check, just check, task test, package scripts, or pre-commit wrappers before inventing ad hoc commands.
Be Collaborative: Never use blamey or ownership-deflecting language such as "not my issue" or "not caused by my change." Describe unrelated failures factually, offer the smallest useful next step, and ask the user whether to handle them now or separately.
Minimal Targeted Changes: Make the smallest coherent change set that solves the task. Do not make opportunistic cleanup edits or random unrelated modifications without approval.
No Silent Descoping: If the task is larger or messier than expected, refine the plan or ask the user how to prioritize. Do not quietly skip work.
Test Integration Over Test Sprawl: New coverage should extend the existing module-path test file and shared fixtures when possible. Do not create one-off issue or feature test files when the behavior belongs in an existing src/tests/{unit,integration}/<module path>/test_*.py module.
PyApp Release Path: Onefile releases use the custom Bundle-Patch-Compile workflow. Keep the PyApp runtime on Python 3.13, force UV_PYTHON/PYAPP_BUILD_PYTHON during make build-onefile, install under the XDG config path, and require Zig/cargo-zigbuild for Linux glibc 2.17 launchers.
Release Container Path: Release containers wrap the onefile binary using the single distroless Dockerfile at tools/deploy/docker/Dockerfile. Wallet-backed runs mount the wallet at /app/wallet; the image sets TNS_ADMIN and WALLET_LOCATION to that path.
CLI Boundary: coffee upgrade is the packaged/end-user install command. Raw SQLSpec developer commands such as downgrade/current stay under python manage.py database ....
Conventional Commits: Commit messages and pull request titles must use Conventional Commits syntax. Do not add host-specific prefixes such as [codex] to PR titles.

Beads Integration

Flow supports two modes:

Official Beads (bd) - default
No Beads - degraded mode for docs/plans/lightweight local work

Configured for local-only use during setup unless the user explicitly asks for shared repo state.

Default setup writes .agents/beads.json with syncPolicy.autoExport: false, syncPolicy.autoGitAdd: false, and syncPolicy.allowDoltPush: false. It also applies bd config set no-git-ops true, bd config set export.auto false, and bd config set export.git-add false, and appends json-envelope: true to .beads/config.yaml to opt into the bd v2.0 JSON envelope.

Session Protocol

Session Start:

Use the active backend's session-start commands. Prefer bd prime --mcp when host hooks inject MCP-aware context; otherwise use bd prime.

Session End:

For local-only ignores, prefer .git/info/exclude before .gitignore. Do not run bd dolt push unless the user explicitly asks or .agents/beads.json opts in with syncPolicy.allowDoltPush. Use prek for manual hook runs: prek run --all-files.

If no supported Beads backend is available, workflow degrades gracefully to git-only tracking.

When to Track in Beads

Rule: If work takes >5 minutes, track it in Beads.

Duration	Action	Example
<5 min	Just do it	Fix typo, update config
5-30 min	Create task	Add validation, write test
30+ min	Create task with subtasks	Implement feature

Why this matters:

Notes survive context compaction - critical for multi-session work
The active Beads backend finds unblocked work automatically
If resuming in 2 weeks would be hard without context, use Beads

Creating Issues with Full Context

CRITICAL: Always include the backend's purpose/description field at creation time, then add context notes separately.

bd create "<task>" -t task -p 2 --description="<purpose and goal>"
bd note <id> "<context for future agents>"

--description: Purpose and goal
notes/comments: Context for future agents
durable cross-session facts: bd remember "..." --key <repo>:<topic>
structured issue context: prefer --context, --design, --acceptance, --metadata, --skills, and --spec-id when available
Priority levels: P0=critical, P1=high, P2=medium, P3=low, P4=backlog

Task Workflow

All tasks follow a strict lifecycle:

Task Workflow (TDD) - Beads-First

CRITICAL: Beads is the source of truth. Never write [x], [~], [!], or [-] markers to spec.md manually. After Beads state changes, follow syncPolicy.flowSyncAfterMutation by using the Flow plugin sync workflow if available, or by explicitly reconciling the markdown view from Beads state. Do not run bd sync; it is not a valid command.

Companion Skills Usage:

Analysis: Use flow:tracer for systematic code exploration before implementation.
Design: Use flow:consensus when choosing between multiple implementation approaches.
Validation: Use flow:challenge when reviewing claims to prevent reflexive agreement.
Debugging: Use flow:deepthink if a problem resists quick answers or investigation goes in circles.
External Docs: Use flow:apilookup for authoritative API/framework docs, versions, breaking changes.
Security: Use flow:security-auditor when touching auth, input handling, secrets, or API keys.
Architecture: Use flow:architecture-critic when adding modules, changing boundaries, or assessing coupling.
Performance: Use flow:performance-analyst for hot paths, DB queries, N+1 detection, caching.
Multiple Views: Use flow:perspectives when weighing trade-offs or evaluating decisions.
Pushback: Use flow:devils-advocate during PR review or when a decision lacks visible opposition.
Documentation: Use flow:docgen when generating API docs, module docs, or reference guides.
Domain Skills: Consult patterns.md Skill Associations table for language, framework, database, and cloud-specific skills.

Select Task: Use the active backend's ready queue, or fall back to parsing spec.md
Mark In Progress:
- Update Beads state using the active backend
- Do NOT edit spec.md - Beads is source of truth
Write Failing Tests (Red Phase):
- First locate the source module under test, then find the matching test module under src/tests/unit/<module path>/ or src/tests/integration/<module path>/.
- Extend the existing module-path test file whenever the behavior belongs to an already-tested module. Prefer adding a parameterized case, shared fixture, or assertion to the existing functional section over creating another file.
- Create a new test file only when no module-path test file exists yet, or when the source module/behavior is genuinely new and the file name maps to that module's public contract.
- Never create new top-level issue/feature buckets such as src/tests/api, direct src/tests/unit/test_*.py, direct src/tests/integration/test_*.py, or regression files named after tickets.
- Write one or more tests that clearly define the expected behavior and acceptance criteria for the task.
- CRITICAL: Run the tests and confirm that they fail as expected. This is the "Red" phase of TDD. Do not proceed until you have failing tests.
Implement to Pass Tests (Green Phase):
- Write the minimum amount of application code necessary to make the failing tests pass.
- Run the test suite again and confirm that all tests now pass. This is the "Green" phase.
Refactor (Optional but Recommended):
- With the safety of passing tests, refactor the implementation code and the test code to improve clarity, remove duplication, and enhance performance without changing the external behavior.
- Rerun tests to ensure they still pass after refactoring.
Verify Coverage: Run coverage reports using the project's chosen tools. For example, in a Python project, this might look like:
```
pytest --cov=app --cov-report=html
```
Target: >80% coverage for new code. The specific tools and commands will vary by language and framework.
Document Deviations: If implementation differs from tech stack:
- STOP implementation
- Update tech-stack.md with new design
- Add dated note explaining the change
- Resume implementation
Commit Code Changes:
- Stage all code changes related to the task.
- Propose a clear, concise commit message e.g, feat(ui): Create basic HTML structure for calculator.
- Perform the commit.
Record Task Completion (Beads-First):
- Step 9.1: Get Commit Hash: Obtain the hash of the just-completed commit (git log -1 --format="%h").
- Step 9.2: Close in Beads: use the active backend to record completion
- Step 9.3 (Markdown View Refresh): Follow syncPolicy.flowSyncAfterMutation; when enabled, use the Flow plugin sync workflow if available, or explicitly update the markdown view from Beads state. Do not run bd sync.
- Do NOT manually edit spec.md markers - refresh markdown through the Flow plugin workflow or explicit Beads-state reconciliation.
Log Learnings:
- Append discoveries to track's learnings.md
- Record in Beads using the active backend's note/comment command
- Elevate reusable patterns to .agents/patterns.md at phase completion
- If the user had to repeat a correction or showed frustration, capture that as a workflow gap and elevate it into the knowledge system
- Capture validated repo-native commands and verification workflows so future agents reuse the same make, just, task, package-script, or pre-commit entrypoints
- If .agents/skills/flow-memory-keeper/SKILL.md exists, update it with durable project-specific refinements

Knowledge Flywheel

Capture - After each task, append learnings to flow's learnings.md
Elevate - At phase/flow completion, move reusable patterns to .agents/patterns.md
Synthesize - During sync and archive, integrate learnings directly into cohesive, logically organized component chapters in .agents/knowledge/guides/ (e.g., architecture.md, oracle-database.md, adk-agent-patterns.md, store-inventory-maps.md, frontend-ui.md, testing-verification.md, operations-packaging.md, settings.md). Update the current state, do NOT outline history.
Archive Research - If a completed flow has a corresponding research directory under .agents/research/, it must be archived with the spec. Move the research directory into the archived flow directory (e.g., .agents/archive/{flow_id}/research/) before closing the epic.
Unlink archive - Treat .agents/archive/ as ignored, disposable local history. Do not leave active docs, guides, indexes, specs, or workflow instructions that require readers to follow links into archive content. If archive content still matters, fold it into .agents/knowledge/ or .agents/patterns.md first.
Inherit - New flows read patterns.md + scan .agents/knowledge/ chapters.

Repeated user corrections or frustration are high-signal learning triggers. Do not leave them buried in chat history; turn them into explicit patterns or knowledge updates. Validated repo-native commands are also high-signal learnings. If the project already has a canonical make lint, make test, make check, just check, task test, or equivalent wrapper, preserve it in this workflow and elevate it when needed.

Knowledge Base:

Tier	File	Loaded	Purpose
Patterns	`.agents/patterns.md`	Always	Elevated actionable rules for priming
Knowledge Chapters	`.agents/knowledge/*.md`	On demand	Synthesized implementation details and current state

Important: .agents/patterns.md is NOT archived with flows. It remains at the top level as persistent project knowledge. Knowledge chapters in .agents/knowledge/ also persist independently of archives and describe the active codebase state. .agents/archive/ is ignored local history; it must not be the only place a durable lesson exists.

Learnings Entry Format:

## [YYYY-MM-DD HH:MM] - Phase N Task M: Task Description

- **Implemented:** Brief description
- **Files changed:** path/to/files
- **Commit:** abc1234
- **Learnings:**
  - Patterns: Codebase uses X for Y
  - Gotchas: Must do Z before W
  - Context: Module A owns B

Phase Completion Verification and Checkpointing Protocol

Trigger: This protocol is executed immediately after a task is completed that also concludes a phase in spec.md.

Announce Protocol Start: Inform the user that the phase is complete and the verification and checkpointing protocol has begun.
Ensure Test Coverage for Phase Changes:
- Step 2.1: Determine Phase Scope: To identify the files changed in this phase, you must first find the starting point. Read spec.md to find the Git commit SHA of the previous phase's checkpoint. If no previous checkpoint exists, the scope is all changes since the first commit.
- Step 2.2: List Changed Files: Execute git diff --name-only <previous_checkpoint_sha> HEAD to get a precise list of all files modified during this phase.
- Step 2.3: Verify and Create Tests: For each file in the list:
  - CRITICAL: First, check its extension. Exclude non-code files (e.g., .json, .md, .yaml).
  - For each remaining code file, verify corresponding coverage exists in the matching src/tests/unit/<module path>/ or src/tests/integration/<module path>/ file.
  - If coverage is missing, first integrate the new case into the existing module-path test file using parameterization or shared fixtures where practical.
  - Create a new test file only when the target source module has no existing module-path test file or the new behavior is substantial enough to deserve a separate module-owned contract file. The new tests must validate the functionality described in this phase's tasks (spec.md).
Execute Automated Tests with Proactive Debugging:
- Before execution, you must announce the exact shell command you will use to run the tests.
- Example Announcement: "I will now run the automated test suite to verify the phase. Command: CI=true npm test"
- Execute the announced command.
- If tests fail, you must inform the user and begin debugging. You may attempt to propose a fix a maximum of two times. If the tests still fail after your second proposed fix, you must stop, report the persistent failure, and ask the user for guidance.

Propose a Detailed, Actionable Manual Verification Plan:

CRITICAL: To generate the plan, first analyze product.md, product-guidelines.md, and spec.md to determine the user-facing goals of the completed phase.
You must generate a step-by-step plan that walks the user through the verification process, including any necessary commands and specific, expected outcomes.

The plan you present to the user must follow this format:

For a Frontend Change:

The automated tests have passed. For manual verification, please follow these steps:

**Manual Verification Steps:**
1.  **Start the development server with the command:** `npm run dev`
2.  **Open your browser to:** `http://localhost:3000`
3.  **Confirm that you see:** The new user profile page, with the user's name and email displayed correctly.

For a Backend Change:

The automated tests have passed. For manual verification, please follow these steps:

**Manual Verification Steps:**
1.  **Ensure the server is running.**
2.  **Execute the following command in your terminal:** `curl -X POST http://localhost:8080/api/v1/users -d '{"name": "test"}'`
3.  **Confirm that you receive:** A JSON response with a status of `201 Created`.

Await Explicit User Feedback:
- After presenting the detailed plan, ask the user for confirmation: "Does this meet your expectations? Please confirm with yes or provide feedback on what needs to be changed."
- PAUSE and await the user's response. Do not proceed without an explicit yes or confirmation.
Create Checkpoint Commit:
- Stage all changes. If no changes occurred in this step, proceed with an empty commit.
- Perform the commit with a clear and concise message (e.g., flow(checkpoint): Checkpoint end of Phase X).
Record Verification in Beads:
- Update the epic with verification summary using the active backend's note/comment command
Sync to spec.md (Manual):
- Follow syncPolicy.flowSyncAfterMutation; when enabled, use the Flow plugin sync workflow if available, or explicitly update spec.md from Beads state for human-readable status.
- Do NOT manually edit task markers in spec.md - Beads is source of truth. Do not run bd sync; it does not exist in this environment.
Announce Completion: Inform the user that the phase is complete and the checkpoint has been recorded in Beads.

Quality Gates

Before marking any task complete, verify:

Development Commands

Setup

make install
uv run python manage.py init --run-install

Daily Development

make start-infra
uv run coffee upgrade
uv run coffee run

Before Committing

make format
make lint
make typecheck
make test

APEX Development (Optional)

make apex
uv run python manage.py infra apex validate --alias cymbal-coffee-ops
uv run python manage.py infra apex import --alias cymbal-coffee-ops
uv run python manage.py infra apex export --app-id <app-id> --alias cymbal-coffee-ops

Testing Requirements

Unit Testing

Every module must have corresponding tests.
Use appropriate test setup/teardown mechanisms (e.g., fixtures, beforeEach/afterEach).
Mock external dependencies.
Test both success and failure cases.

Integration Testing

Test complete user flows
Verify database transactions
Test authentication and authorization
Check form submissions

Mobile Testing

Test on actual iPhone when possible
Use Safari developer tools
Test touch interactions
Verify responsive layouts
Check performance on 3G/4G

Code Review Process

Self-Review Checklist

Before requesting review:

Functionality
- Feature works as specified
- Edge cases handled
- Error messages are user-friendly
Code Quality
- Follows style guide
- DRY principle applied
- Clear variable/function names
- Appropriate comments
Testing
- Unit tests comprehensive
- Integration tests pass
- Coverage adequate (>80%)
Security
- No hardcoded secrets
- Input validation present
- SQL injection prevented
- XSS protection in place
Performance
- Database queries optimized
- Images optimized
- Caching implemented where needed
Mobile Experience
- Touch targets adequate (44x44px)
- Text readable without zooming
- Performance acceptable on mobile
- Interactions feel native

Commit Guidelines

Message Format

<type>(<scope>): <description>

[optional body]

[optional footer]

Types

feat: New feature
fix: Bug fix
docs: Documentation only
style: Formatting, missing semicolons, etc.
refactor: Code change that neither fixes a bug nor adds a feature
test: Adding missing tests
chore: Maintenance tasks

Examples

git commit -m "feat(auth): Add remember me functionality"
git commit -m "fix(posts): Correct excerpt generation for short posts"
git commit -m "test(comments): Add tests for emoji reaction limits"
git commit -m "style(mobile): Improve button touch targets"

Definition of Done

A task is complete when:

All code implemented to specification
Unit tests written and passing
Code coverage meets project requirements
Documentation complete (if applicable)
Code passes all configured linting and static analysis checks
Works beautifully on mobile (if applicable)
Implementation notes added to spec.md
Changes committed with proper message
Task closed in Beads with the active backend's completion command and commit reference
Markdown views refreshed through the Flow plugin workflow or explicit Beads-state reconciliation; never by running bd sync.
No ignored Flow artifacts were force-added to git.

Emergency Procedures

Critical Bug in Production

Create hotfix branch from main
Write failing test for bug
Implement minimal fix
Test thoroughly including mobile
Deploy immediately
Document in spec.md

Data Loss

Stop all write operations
Restore from latest backup
Verify data integrity
Document incident
Update backup procedures

Security Breach

Rotate all secrets immediately
Review access logs
Patch vulnerability
Notify affected users (if any)
Document and update security procedures

Deployment Workflow

Pre-Deployment Checklist

Deployment Steps

Merge feature branch to main
Tag release with version
Push to deployment service
Run database migrations
Verify deployment
Test critical paths
Monitor for errors

Post-Deployment

Monitor analytics
Check error logs
Gather user feedback
Plan next iteration

Continuous Improvement

Review workflow weekly
Update based on pain points
Document lessons learned
Capture user corrections, missing defaults, and canonical repo commands so they stop being chat-only reminders
Optimize for user happiness
Keep things simple and maintainable

FilesExpand file tree

workflow.md

Latest commit

History

workflow.md

File metadata and controls

Project Workflow

Essential Commands

Daily Development

Before Committing

Build And Release

Guiding Principles

Beads Integration

Session Protocol

Session End:

When to Track in Beads

Creating Issues with Full Context

Task Workflow

Task Workflow (TDD) - Beads-First

Knowledge Flywheel

Phase Completion Verification and Checkpointing Protocol

Quality Gates

Development Commands

Setup

Daily Development

Before Committing

APEX Development (Optional)

Testing Requirements

Unit Testing

Integration Testing

Mobile Testing

Code Review Process

Self-Review Checklist

Commit Guidelines

Message Format

Types

Examples

Definition of Done

Emergency Procedures

Critical Bug in Production

Data Loss

Security Breach

Deployment Workflow

Pre-Deployment Checklist

Deployment Steps

Post-Deployment

Continuous Improvement