# AGENTS.md — Build guide for Reclaim.ai

## Project scope
Schedule one owner's flexible tasks and habits into free calendar windows, preview a proposed plan and apply approved holds. Replan only tool-owned holds when meetings move, preserving protected focus periods.

Catalogue verdict: kinda. A personal auto-blocker is buildable, but two-way calendar sync, scheduling links, team features, and conflict-safe automation are upkeep-heavy.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- Node, one Google Calendar OAuth client with the necessary consent/scopes, user-controlled task configuration and secure refresh-token storage. No public booking frontend is needed.
- Implementation components: Node.js CLI, googleapis and a timezone-aware scheduler for one Google Calendar. A versioned YAML task/habit configuration and SQLite operation receipts; plan/apply commands separate preview from calendar writes.
- Scope boundary: Team coordination and broad provider support are outside scope.

## Stack and architecture
- Node.js CLI, googleapis and a timezone-aware scheduler for one Google Calendar.
- A versioned YAML task/habit configuration and SQLite operation receipts; plan/apply commands separate preview from calendar writes.
- Domain model: task estimates, habit windows, owned calendar holds, schedule revisions and provider event mappings

## Security and data integrity
- Encrypt refresh tokens with a separately managed key; expose busy intervals rather than event titles publicly. Hash guest management tokens and bound their lifetime.
- Correctness boundary: Never move or delete events the tool did not create; every automated change is tied to a plan revision and can be reviewed or reverted.
- Store UTC instants plus the intended IANA timezone. Reserve locally in a transaction, recheck provider availability, create with a stable external ID, then reconcile timeouts before retrying.
- Export task configuration and tool-owned event mappings. The apply command records enough prior event state to review a rollback; it never deletes non-owned calendar events.

## Agent implementation rules
- Project rule — data model: task estimates, habit windows, owned calendar holds, schedule revisions and provider event mappings
- Project rule — preserve this invariant: Never move or delete events the tool did not create; every automated change is tied to a plan revision and can be reviewed or reverted.
- Project rule — acceptance evidence: Add a conflicting external meeting and move only the affected owned hold; rerunning the same plan creates no duplicate events.

## Optional agent skills and references
- Optional external skill: [gws-calendar](https://github.com/googleworkspace/cli/blob/main/skills/gws-calendar/SKILL.md) — Use Google Calendar calendars, events, recurrence, free/busy queries and integration discovery through the gws CLI. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.
- Optional external skill: [sharp-edges](https://github.com/trailofbits/skills/blob/main/plugins/sharp-edges/skills/sharp-edges/SKILL.md) — Review security-sensitive APIs and configuration for dangerous defaults and easy-to-misuse interfaces. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate the actual Reclaim.ai-inspired workflow with owned or clearly labeled sample data: Schedule one owner's flexible tasks and habits into free calendar windows, preview a proposed plan and apply approved holds. Replan only tool-owned holds when meetings move, preserving protected focus periods.
- Publish a reproducible walkthrough with this observable result: Add a conflicting external meeting and move only the affected owned hold; rerunning the same plan creates no duplicate events.
- Explain who can operate this scoped tool, its setup and ongoing costs, and these remaining product gaps: Team coordination and broad provider support are outside scope. Avoid guaranteed savings, performance scores or implied endorsement.

## Engineering roadmap
1. Phase 1 — Scope and fixtures. Implement this bounded workflow: Schedule one owner's flexible tasks and habits into free calendar windows, preview a proposed plan and apply approved holds. Replan only tool-owned holds when meetings move, preserving protected focus periods. Record prerequisites, select representative user-owned fixtures and document the unsupported features: Team coordination and broad provider support are outside scope.
2. Phase 2 — Durable model. Model task estimates, habit windows, owned calendar holds, schedule revisions and provider event mappings Add migrations or a versioned document format, explicit validation, stable IDs and a visible import-error report. Preserve this rule: Never move or delete events the tool did not create; every automated change is tied to a plan revision and can be reviewed or reverted.
3. Phase 3 — Complete the first useful path. Implement the workflow's input, review and output interface, with clear controls and explicit empty/error states. Store UTC instants plus the intended IANA timezone. Reserve locally in a transaction, recheck provider availability, create with a stable external ID, then reconcile timeouts before retrying.
4. Phase 4 — Permissions and integration failure. Encrypt refresh tokens with a separately managed key; expose busy intervals rather than event titles publicly. Hash guest management tokens and bound their lifetime. Request integration credentials and permissions only for the enabled feature; show a disconnected state instead of mock results.
5. Phase 5 — Portable handoff. Export task configuration and tool-owned event mappings. The apply command records enough prior event state to review a rollback; it never deletes non-owned calendar events. Include setup, operating limits, fixture walkthrough and shutdown/restart instructions in the README.
6. Phase 6 — Acceptance scenarios. Add a conflicting external meeting and move only the affected owned hold; rerunning the same plan creates no duplicate events. Repeat the workflow after restart and with a denied permission or unavailable dependency; show recoverable failure rather than a success placeholder.

## Paid-product capabilities outside this build
- team coordination
- smart rescheduling polish
- scheduling links
- calendar edge cases
- uptime

## Implementation prompt
WORKING SLICE
Schedule one owner's flexible tasks and habits into free calendar windows, preview a proposed plan and apply approved holds. Replan only tool-owned holds when meetings move, preserving protected focus periods.

Build this scoped Reclaim.ai-inspired workflow with a documented data model and visible failure states.

Architecture
- Node.js CLI, googleapis and a timezone-aware scheduler for one Google Calendar.
- A versioned YAML task/habit configuration and SQLite operation receipts; plan/apply commands separate preview from calendar writes.

Prerequisites and limits
Node, one Google Calendar OAuth client with the necessary consent/scopes, user-controlled task configuration and secure refresh-token storage. No public booking frontend is needed.
Outside this release: Team coordination and broad provider support are outside scope.

Data model and correctness
task estimates, habit windows, owned calendar holds, schedule revisions and provider event mappings
Invariant: Never move or delete events the tool did not create; every automated change is tied to a plan revision and can be reviewed or reverted.
Store UTC instants plus the intended IANA timezone. Reserve locally in a transaction, recheck provider availability, create with a stable external ID, then reconcile timeouts before retrying.

Security and privacy
Encrypt refresh tokens with a separately managed key; expose busy intervals rather than event titles publicly. Hash guest management tokens and bound their lifetime.

Recovery and export
Export task configuration and tool-owned event mappings. The apply command records enough prior event state to review a rollback; it never deletes non-owned calendar events.

Implementation order
1. Phase 1 — Scope and fixtures. Implement this bounded workflow: Schedule one owner's flexible tasks and habits into free calendar windows, preview a proposed plan and apply approved holds. Replan only tool-owned holds when meetings move, preserving protected focus periods. Record prerequisites, select representative user-owned fixtures and document the unsupported features: Team coordination and broad provider support are outside scope.
2. Phase 2 — Durable model. Model task estimates, habit windows, owned calendar holds, schedule revisions and provider event mappings Add migrations or a versioned document format, explicit validation, stable IDs and a visible import-error report. Preserve this rule: Never move or delete events the tool did not create; every automated change is tied to a plan revision and can be reviewed or reverted.
3. Phase 3 — Complete the first useful path. Implement the workflow's input, review and output interface, with clear controls and explicit empty/error states. Store UTC instants plus the intended IANA timezone. Reserve locally in a transaction, recheck provider availability, create with a stable external ID, then reconcile timeouts before retrying.
4. Phase 4 — Permissions and integration failure. Encrypt refresh tokens with a separately managed key; expose busy intervals rather than event titles publicly. Hash guest management tokens and bound their lifetime. Request integration credentials and permissions only for the enabled feature; show a disconnected state instead of mock results.
5. Phase 5 — Portable handoff. Export task configuration and tool-owned event mappings. The apply command records enough prior event state to review a rollback; it never deletes non-owned calendar events. Include setup, operating limits, fixture walkthrough and shutdown/restart instructions in the README.
6. Phase 6 — Acceptance scenarios. Add a conflicting external meeting and move only the affected owned hold; rerunning the same plan creates no duplicate events. Repeat the workflow after restart and with a denied permission or unavailable dependency; show recoverable failure rather than a success placeholder.

Acceptance
Add a conflicting external meeting and move only the affected owned hold; rerunning the same plan creates no duplicate events.
Use real source data or clearly labeled fixtures. Explain unsupported input and provider failures; do not fabricate analytics, delivery receipts, accuracy claims or security guarantees.

Optional agent guidance
Optional external skill: [gws-calendar](https://github.com/googleworkspace/cli/blob/main/skills/gws-calendar/SKILL.md) — Use Google Calendar calendars, events, recurrence, free/busy queries and integration discovery through the gws CLI. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.
Optional external skill: [sharp-edges](https://github.com/trailofbits/skills/blob/main/plugins/sharp-edges/skills/sharp-edges/SKILL.md) — Review security-sensitive APIs and configuration for dangerous defaults and easy-to-misuse interfaces. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.
Project rule — data model: task estimates, habit windows, owned calendar holds, schedule revisions and provider event mappings
Project rule — preserve this invariant: Never move or delete events the tool did not create; every automated change is tied to a plan revision and can be reviewed or reverted.
Project rule — acceptance evidence: Add a conflicting external meeting and move only the affected owned hold; rerunning the same plan creates no duplicate events.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.