todowai

Imported from sunix/todowai (AGENTS.md). Install upstream with npx skills add sunix/todowai. Copyright stays with the author.

Agent Instructions

Current Phase

Phase: 4 — Implementation Iteration: 1 Status: In Progress

Project Overview

Todowai is a personal notes and task application that keeps track of what a person has done, is doing, and wants to do in an Obsidian-style Markdown workspace. The product should let the user capture and edit notes from mobile, browser, and desktop clients, then use AI to reorganize those notes, help follow projects, support delegated AI work, and suggest what to do next across large tasks, parallel work, and meetings.

Phases

This project moves through five sequential phases. Each phase has its own folder. The agent must not advance to the next phase without explicit human confirmation.

Phase 1 — Specification (specification/)

Goal: Produce a clear, agreed-upon specification in specification/specs.md.

How it works:

• Kick-off (once): the human dumps raw material — notes, a brain dump, an existing document — into specification/scratch.md (or points the agent at any file / pasted text). The agent runs the import-specs skill to turn it into the first structured draft of specification/specs.md.
• Iterate: from there the human owns specification/specs.md. The agent assists via the refine-specs skill: asking clarifying questions, surfacing gaps, and suggesting structure improvements.
• Multiple iterations are expected. Each iteration increments the iteration count in Current Phase.
• Phase 1 is complete when the human explicitly marks specs as ready to prototype.
• Significant, hard-to-reverse decisions (and the reasoning behind them) are recorded in specification/decisions.md — a running ADR-style log, separate from specs.md itself. specs.md describes the current target state; decisions.md preserves the why behind pivots so it isn't lost as specs evolve. Check it at the start of work, and append a new entry whenever a decision changes direction on something already decided or already built.

Skills:

• .agents/skills/import-specs/SKILL.md — seed the first draft from raw input
• .agents/skills/refine-specs/SKILL.md — iterate on the draft

Phase 2 — Mockup (mockup/)

Goal: Produce a fully clickable HTML prototype in mockup/ derived from the specification.

How it works:

• Triggered by the generate-mockup skill once Phase 1 is marked complete.
• The agent generates a self-contained, fully navigable HTML mockup reflecting specification/specs.md.
• The human reviews and provides feedback. Feedback triggers one of two outcomes:
  1. Iterate on mockup: agent refines the prototype (increments iteration, stays in Phase 2).
  2. Back to specs: agent invokes sync-specs-from-mockup to update specification/specs.md, re-enters Phase 1.

Deployment: Every push to main that touches mockup/ automatically deploys to GitHub Pages via .github/workflows/deploy-mockup.yml. The prototype is publicly accessible at https://<org-or-user>.github.io/<repo-name>/. Requires Pages source set to GitHub Actions in repository settings.

Skills:

• .agents/skills/generate-mockup/SKILL.md
• .agents/skills/sync-specs-from-mockup/SKILL.md

Phase 3 — Plan (plan/)

Goal: Produce actionable implementation, deployment, and monitoring plans with corresponding GitHub issues.

How it works:

• Triggered by the create-plan skill once Phase 2 is marked complete.
• The agent creates three plan documents under plan/:
  • plan/implementation.md
  • plan/deployment.md
  • plan/monitoring.md
• For each action item, the agent creates a GitHub issue (via gh) and embeds the issue URL back in the plan document.
• The human reviews and adjusts priorities before development begins.

Skill: .agents/skills/create-plan/SKILL.md

Phase 4 — Implementation (implementation/)

Goal: Turn the plan into a working, deployed application by executing the Phase 3 GitHub issues with AI coding agents, until the first version runs in QA/staging.

How it works:

• Triggered by the implement skill once Phase 3 is marked complete and the issues are prioritised.
• Work through the planned issues in priority order. Each issue is routed to an AI coding agent via its AI Coding Agent label:
  • Claude (agent:claude label) — a team member opens a Claude Code session, implements the issue on a feature branch, and opens a PR that closes it.
  • GitHub Copilot (agent:copilot label) — assign the issue to @copilot in the GitHub UI, or click "Request Copilot" on the issue page. Copilot opens a draft PR autonomously. Works best for issues with clear, self-contained acceptance criteria.
• Humans review and merge the PRs. Progress is tracked in implementation/progress.md. Each work round increments the iteration count in Current Phase.
• Phase 4 is complete when the planned scope is implemented, tested, and deployed to QA/staging.

Agent routing cheat-sheet:

Skill: .agents/skills/implement/SKILL.md

Phase 5 — Operate (operate/)

Goal: Sustain a continuous feedback loop between live users and AI coding agents once the application is running in staging or production.

How it works:

• Users submit feature requests and bug reports through GitHub Issues using the structured templates in .github/ISSUE_TEMPLATE/.
• Each issue carries the same AI Coding Agent preference field and is routed exactly as in Phase 4 (see the routing cheat-sheet above): agent:claude or agent:copilot.
• The issue-template-maker skill is run once to install project-aware templates and create the required labels in the repository.
• There is no fixed end to Phase 5 — it runs continuously alongside the live application.

Skill: .agents/skills/issue-template-maker/SKILL.md

Phase Progression

Use the update-phase skill to advance to the next phase or record a new iteration.

Invoking Skills

Type any skill name as a standalone message to invoke it — no extra phrasing needed:

import-specs
refine-specs
generate-mockup
create-plan
implement
update-phase

The agent will recognise the skill name, load the corresponding file from .agents/skills/, and execute it. Typing help lists all available skills for the current project.

Skills

Commit & PR Conventions

Required from Phase 3 onward, since release-please (see plan/deployment.md) computes version bumps from commit history on main:

• Conventional Commits for every commit message and pull request title: <type>[optional scope]: <description> (e.g. feat: add capture drafting, fix(sync): handle offline pull failure).
  • feat: → minor version bump
  • fix: → patch version bump
  • feat!: or a BREAKING CHANGE: footer → major version bump
  • chore:, docs:, ci:, refactor:, test: → no version bump (still recorded in the changelog)
• One logical commit per pull request — squash intermediate commits before opening or updating a PR, so main's history stays release-please-friendly.
  • Exception: once a PR branch already has commits pushed (e.g. review feedback, a previous update), don't squash/force-push over them — append new commits instead, so reviewers keep a stable history to diff against.
• Preview builds — after pushing a commit to a PR, comment /preview on the PR to trigger the Surge preview deployment (see .github/workflows/preview-pr.yml). The bot replies with a preview link once the build finishes.
• Playwright-verified UI changes — whenever a PR's testing drives the app with Playwright (an end-to-end flow, a visual check), attach at least one screenshot of the result directly in the PR description, not just a text description of what was tested. The goal is that a visual review of a UI change never requires pulling the branch and clicking through it manually to see whether it worked.
• Post-merge recap — once a PR is merged, add a recap comment on the GitHub issue it closes, summarising what shipped and including screenshots when the change is visual (UI, mockup, etc.).

Constraints

• Keep personal notes and task history as private as possible.
• Preserve an Obsidian-style Markdown note-taking model.
• Support note access and editing from mobile, browser, and desktop environments.
• Handle mobile and PC usage in parallel without blocking concurrent edits.
• Store notes and AI conversations in a single user-configurable private git repository (dedicated subfolder for conversations), not one hardcoded by the app.
• Do not implement note/conversation content encryption in v1; rely on private-repo + git transport security instead (GPG/content encryption deferred).
• Do not let the AI write to external services (e.g. calendar, email) or execute autonomously outside the note base; delegated AI work is limited to reviewable edits within the repo, always confirmed by the user.