TaskFlow

A task manager built to demonstrate one thing: how to build software the right way with AI.

Not about functional complexity. About process, standards, and traceability — from product idea to production code.

---

What This Project Demonstrates

• Full traceability: PRD → Specs → Design → Tasks → Code → Verification
• AI agents that follow your standards, not their own assumptions
• A monorepo structured so every workspace knows its own rules
• Professional conventions enforced through context — not reminders
• A development workflow that scales across tools, teams, and AI assistants

---

Monorepo Structure

/
├── ui/                  ← React 19 frontend
│   ├── AGENTS.md        ← UI-specific agent instructions
│   ├── docs/            ← Frontend architecture & decisions
│   └── src/
├── api/                 ← Node.js + Express backend (coming soon)
│   ├── AGENTS.md        ← API-specific agent instructions
│   └── docs/
├── docs/                ← Project-wide documentation (PRD, architecture, workflow)
├── skills/              ← Project skills loaded by AI agents
│   ├── new-feature/     ← End-to-end feature guide (SDD + TDD)
│   ├── new-endpoint/    ← REST endpoint guide
│   ├── integrate-api/   ← Mock → real API migration guide
│   ├── commit/          ← Conventional Commits guide
│   ├── pull-request/    ← PR workflow with gh CLI
│   ├── react-19/        ← React 19 + Compiler patterns
│   └── ...
├── AGENTS.md            ← Root agent entry point
└── README.md

---

Tech Stack

Layer	Technology
Frontend	React 19, Vite, TypeScript strict, TailwindCSS v4
State	Zustand 5
Testing	Vitest, React Testing Library
Backend	Node.js, Express, TypeScript (coming soon)
Database	PostgreSQL + Prisma (coming soon)

---

Getting Started

cd ui
npm install
npm run dev        # dev server → localhost:5173
npm test           # 28/28 unit tests
npm run typecheck  # TypeScript — must pass with 0 errors

---

The AGENTS.md Philosophy

This project uses a layered AGENTS.md system to give AI agents the right context at the right scope — without overwhelming them with everything at once.

The Layered Context Model

AGENTS.md             ← Root: monorepo map, all available skills, global conventions
└── ui/AGENTS.md      ← UI scope: React patterns, testing rules, component conventions
└── api/AGENTS.md     ← API scope: endpoint patterns, auth rules, DB conventions

When an AI agent starts working, it reads the root AGENTS.md first. That file acts as the entry point: it describes the monorepo, lists all available skills, and defines auto-invoke rules. Then the agent reads the workspace-specific AGENTS.md for the area it's actually working in.

This means:

• An agent working in ui/ loads React 19 patterns, Zustand conventions, and Vitest rules
• An agent working in api/ loads REST endpoint patterns and database conventions
• Neither agent gets confused by the other workspace's rules

The scope model also works for human developers: the AGENTS.md files double as living documentation that describes exactly how each part of the system is supposed to be built.

---

Two Types of Skills

Not all skills are the same. This project separates them into two clear categories:

Stack Skills — How to write code

Stack skills encode technical knowledge about a specific library or framework. They answer questions like: "How do we use React 19 in this project? What patterns do we follow with Zustand? How do we write Zod schemas?"

Skill	Purpose
react-19	React 19 + Compiler patterns, no manual memoization
typescript	Strict TypeScript — types, interfaces, generics
tailwind-4	Tailwind v4 utility patterns + cn() usage
zustand-5	Zustand 5 store patterns and slice architecture
zod-4	Zod 4 schema validation, breaking changes from v3
playwright	E2E test structure with Page Objects

These skills capture the decisions your team has already made. When the agent writes a component, it follows your React patterns — not the generic ones it was trained on.

Process Skills — How to work

Process skills encode your development workflow. They answer questions like: "How do we create a new feature end-to-end? What's the PR format? How do we write commit messages?"

Skill	Purpose
new-feature	End-to-end feature guide: SDD planning → TDD implementation → PR
new-endpoint	REST endpoint lifecycle: spec → implementation → tests
integrate-api	Seam migration guide: replacing mocks with real API calls
commit	Conventional Commits format, scope rules, breaking changes
pull-request	PR creation with gh CLI, description format, review checklist

Process skills are the difference between an AI that writes code and an AI that participates in your engineering process. When you ask for a new feature, the agent doesn't just write code — it follows your team's full workflow from proposal to deployment.

Auto-Invoke: Skills Load When They're Needed

Neither type of skill gets loaded globally. The AGENTS.md files define auto-invoke rules — mappings from actions to skills. When an agent detects a matching action, the relevant skill loads automatically:

Action	Skill loaded
Adding a new UI feature	new-feature
Adding an API endpoint	new-endpoint
Connecting UI to real API	integrate-api
Writing a commit message	commit
Opening a Pull Request	pull-request
Writing React components	react-19
Writing TypeScript types	typescript
Working with Tailwind	tailwind-4
Using Zustand stores	zustand-5
Creating Zod schemas	zod-4
Writing E2E tests	playwright

You don't have to remind the agent how to do things. The right skill loads at the right moment, automatically.

---

Standards for the Whole Team, Not Just AI

This is the part that gets overlooked: AGENTS.md and skills are not just AI configuration files. They are team conventions written down in a structured, enforceable format.

Before this kind of system existed, conventions lived in your head, in a Confluence page nobody reads, or in review comments like "we don't do it that way here." They were invisible to new team members, inconsistently applied, and completely inaccessible to AI tools.

With this system:

For human developers — the AGENTS.md and skill files are the source of truth for how work gets done. How to name a component, how to structure a store, how to write a PR description. No more guessing, no more asking senior devs the same questions repeatedly.

For AI agents — the same files serve as the context that shapes every response. The agent writing code in ui/ follows the same React patterns your team agreed on, because those patterns are explicitly documented in ui/AGENTS.md and skills/react-19/SKILL.md.

For onboarding — a new developer (or a new AI tool) starts from the same place. The conventions are in the repo. They're versioned. They evolve with the codebase.

---

Tool-Agnostic by Design

The AGENTS.md + skills system works across any AI coding tool that supports context files:

Tool	How it picks up AGENTS.md
OpenCode	Native — reads AGENTS.md hierarchy automatically
Claude Code	Native — reads CLAUDE.md in working directory and parents
Cursor	Via .cursorrules or AGENTS.md (with configuration)
GitHub Copilot	Via custom instructions files
Windsurf	Via .windsurfrules or instructions files
Any agent/CLI	Skills can be referenced or injected as system prompts

The core idea is the same across all of them: put your conventions in text files that live in the repo, and point your AI tools at them. The format might vary slightly between tools, but the philosophy is portable.

This means your team isn't locked into any single AI tool. Switch from Cursor to Claude Code? Your standards come with you. Try a new agent framework? The skills translate. The knowledge lives in the repo, not in any vendor's platform.

---

Adopting This Workflow

The system is incremental. You don't need to set everything up on day one:

1. Start with a root AGENTS.md — describe your project, your stack, your basic conventions
2. Add a process skill — start with commit or pull-request, the highest-ROI habits
3. Add stack skills as you hit inconsistencies — when the agent writes code differently than your team does, write a skill that captures the right way
4. Add workspace-scoped AGENTS.md files as your project grows and workspaces diverge
5. Add auto-invoke rules to wire actions to skills so nothing gets forgotten

Each step makes the AI more aligned with your team. Each skill written is a convention that will never be forgotten again.

---

Documentation

Path	Contents
docs/	PRD, architecture decisions, development workflow
ui/docs/	Frontend architecture, component guide, state management
api/docs/	REST API design, database schema, endpoint reference
skills/	All workflow and stack skill files
AGENTS.md	Root agent entry point — start here