Give your agents context.
Build with intention.
Turn ideas into working software with project knowledge, reusable skills, clear specs, and changes you can verify.
One idea. A connected workflow.
Follow a notification-preferences feature from first question to final handoff. Illustrative example
Start with what’s already true.
Before an agent changes your project, help it find the architecture, decisions, and constraints that matter to the task.
- Start with
- A feature idea + your repository
- Leave with
- Relevant project knowledge
Notification preferences
Project context for the example feature. Read this before changing how reminders are sent.
- Current behaviour
- Members receive a daily reminder at their chosen time.
- Existing boundary
- The server owns preferences. The scheduler checks them before sending.
- Constraint
- Turning off reminders must not disable account or security messages.
Start: AGENTS.md
Index: docs/_index.md
Read: docs/notifications.mdA compact map first. The relevant page next.
Resolve the questions that change the work.
Challenge the idea, inspect existing behaviour, and settle the decisions that would otherwise turn into guesswork during implementation.
- Start with
- Project context + an open question
- Leave with
- A clear, bounded direction
What does “pause reminders” mean?
Decision: add a single daily-reminder toggle to Settings. Start with the smallest useful change.
- Decide
- The preference applies to daily reminders on every signed-in device.
- Preserve
- Existing members keep their current reminder setting.
- Exclude
- Quiet hours, per-channel controls, and temporary snoozing are future work.
- Verify
- Test saving the preference and the scheduler’s decision to send.
Record the decision and its reason, not the whole conversation.
Make the intended behaviour explicit.
Turn the agreed direction into a shared contract: the problem, scope, acceptance criteria, and how the behaviour will be tested.
- Start with
- Agreed decisions
- Leave with
- An implementable specification
Let members control daily reminders
Members can turn daily reminders on or off in Settings without affecting other messages.
- Accept 01
- The saved preference appears when Settings opens, including on another device.
- Accept 02
- Switching off prevents future daily reminders after the save succeeds.
- Accept 03
- A failed save restores the previous setting and offers a retry.
- Accept 04
- Account and security messages remain unchanged.
Acceptance criteria describe behaviour a person can observe.
Slice the work into verifiable changes.
Give each ticket a useful outcome and explicit dependencies. Start work only when its blockers are complete.
- Start with
- An agreed specification
- Leave with
- Small tickets with blocking relationships
One feature. Three complete slices.
Each ticket connects the behaviour to its verification. The order follows real dependencies.
- 01 · No blockers
- Persist a reminder preference and enforce it in the scheduler. Verify defaults and message exclusions.
- 02 · Blocked by 01
- Expose the saved preference in Settings. Verify a successful change across sessions.
- 03 · Blocked by 02
- Complete failure recovery and keyboard interaction. Verify retry, rollback, and focus.
Small fixes can skip ticket breakdown. Structure should fit the work.
Give each agent a bounded piece of work.
Keep the spec, relevant context, and completion criteria within reach. Implement a ready ticket, then inspect and test the resulting change.
- Start with
- A ready ticket + its context
- Leave with
- A scoped, reviewable change
Implement ticket 02
Read the spec and the preferences contract delivered by ticket 01. Follow the existing Settings patterns.
- Scope
- Show the current value, save a changed value, and display the confirmed result.
- Reuse
- Use the existing preferences client and accessible switch component.
- Check
- Verify initial loading, successful saving, and persistence after reopening Settings.
- Handoff
- Describe the change and test results. Leave failure recovery visible as ticket 03.
Parallel work is useful when the tasks are actually independent.
Finish with evidence. Leave better context.
Review the change against the spec, fix confirmed issues, and update the project docs. Report what was checked and what still needs to happen.
- Start with
- Implementation + acceptance criteria
- Leave with
- Review evidence + updated documentation
A handoff you can inspect
Illustrative report format only. These are example statuses, not tests run against an application.
- Local checks · Passed in example
- Preference persistence, scheduler exclusions, failed-save recovery, and keyboard interaction.
- Review · Resolved in example
- Confirmed the disabled setting leaves security messages unchanged.
- Documentation · Updated in example
- The notification contract now includes the preference and its default.
- Deployment · Not performed
- Hosted checks and post-deployment acceptance are separate evidence.
A passing local check is evidence for that check, not proof of deployment.
Use the whole loop for a feature. Take a shorter path for a small fix. Keep the context and the checks.
A good agent starts
with a good map.
Your project already has a history. Make its architecture, decisions, and constraints easy to find before asking an agent to change them.
Explore indexing optionsAGENTS.md The starting point guardrails.md Your project boundaries docs/ Project knowledge _index.md A map of the knowledge architecture.md How the pieces fit decisions.md What was decided, and why development.md How to work in this repo docs/_index.md Start here
Small entry point.
Useful depth.
AGENTS.md routes the task. A compact documentation index
helps agents find the relevant pages without reading the whole project.
Start with linked Markdown; add search or wiki tooling as your knowledge
grows.
Keep reusable procedures in your skills directory. Keep project-specific knowledge in the repository. Update the relevant page when the behaviour changes.
An index makes knowledge discoverable.
Keeping it accurate is part of the work.
A skill for the job
in front of you.
Small, reusable procedures with clear inputs and useful outputs. Start with these six original templates and adapt them to your project.
How to install the skills Plan Find the right problem. shape-work
Clarify the outcome, challenge assumptions, and record the decisions that matter.
- Input
- An idea or unresolved problem
- Output
- Decisions, scope, and open questions
Specify Make the outcome clear. write-spec
Turn settled decisions into observable behaviour and acceptance criteria.
- Input
- Agreed direction and project context
- Output
- A specification with a verification plan
Organise Make the next step small. slice-work
Break a spec into complete slices with explicit blockers and a way to verify each.
- Input
- An agreed specification
- Output
- Dependency-linked ticket drafts
Build Build one useful change. implement-slice
Implement a ready ticket within the project’s existing patterns and boundaries.
- Input
- A ready ticket, its spec, and context
- Output
- A scoped change and check results
Verify Check what actually changed. review-change
Review behaviour against the spec and identify concrete, actionable regressions.
- Input
- A defined diff and expected behaviour
- Output
- Evidence-backed findings or review limits
Maintain Leave the map up to date. maintain-context
Update the existing topic when behaviour changes, then check the docs and index.
- Input
- Verified changes and current documentation
- Output
- Accurate, discoverable project knowledge
A skill is a folder with a SKILL.md file. Your agent’s setup
determines where it lives and how you invoke it. Explore the format.
“Done” deserves
a little evidence.
A generated change is the beginning of verification. Review the diff, check the behaviour, and leave a handoff someone else can follow.
Keep local checks, hosted CI, and deployment status separate. Then update the docs so the next task starts with better context.
Read the handoff templateDaily reminder preferences
- Changed
- Members can control daily reminders in Settings.
- Checked
- Persistence, scheduler behaviour, failure recovery, and keyboard access.
- Still to do
- Hosted CI and post-deployment acceptance.
- Knowledge
- Notification contract updated with the new preference.
Illustrative only. A report should include the actual commands and results.
Make your next feature
a better starting point.
Take the skills, the templates, and the worked example.
Bring your own repository.