diff --git a/README.md b/README.md index f235414..b1d53bb 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # claude-code-best-practice practice makes claude perfect -![Last Updated](https://img.shields.io/badge/Last_Updated-Mar%2012%2C%202026%2012%3A22%20PM%20PKT-white?style=flat&labelColor=555) GitHub Stars +![Last Updated](https://img.shields.io/badge/Last_Updated-Mar%2012%2C%202026%2006%3A29%20PM%20PKT-white?style=flat&labelColor=555) GitHub Stars [![Best Practice](!/tags/best-practice.svg)](best-practice/) *Click on this badge to show the latest best practice*
[![Implemented](!/tags/implemented.svg)](implementation/) *Click on this badge to show implementation in this repo*
diff --git a/agent-teams/.claude/agents/time-agent.md b/agent-teams/.claude/agents/time-agent.md new file mode 100644 index 0000000..829ccd6 --- /dev/null +++ b/agent-teams/.claude/agents/time-agent.md @@ -0,0 +1,23 @@ +--- +name: time-agent +description: Use this agent to fetch the current time for Dubai, UAE (Asia/Dubai timezone, UTC+4). This agent fetches real-time Dubai time using its preloaded time-fetcher skill. +tools: Bash +model: haiku +color: blue +maxTurns: 3 +skills: + - time-fetcher +--- + +You are the time-agent. Your job is to fetch the current Dubai time. + +## Instructions + +1. Use the Bash tool to run: `TZ='Asia/Dubai' date '+%Y-%m-%d %H:%M:%S %Z'` +2. Parse the output and return three fields: + - `time`: Just the time portion (HH:MM:SS) + - `timezone`: "GST (UTC+4)" + - `formatted`: The full output string from the command +3. Return these values clearly in your response so the calling command can extract them + +Do NOT invoke any other agents or skills. diff --git a/agent-teams/.claude/commands/time-orchestrator.md b/agent-teams/.claude/commands/time-orchestrator.md new file mode 100644 index 0000000..e2ea9df --- /dev/null +++ b/agent-teams/.claude/commands/time-orchestrator.md @@ -0,0 +1,50 @@ +--- +model: haiku +--- + +# Time Orchestrator Command + +Fetch the current time for Dubai (Asia/Dubai, UTC+4) and create a visual SVG time card. + +## Workflow + +### Step 1: Fetch Current Dubai Time + +Use the Agent tool to invoke the time agent: +- subagent_type: time-agent +- description: Fetch current Dubai time +- prompt: Fetch the current time for Dubai (Asia/Dubai, UTC+4). Return exactly three fields: `time` (the time portion, e.g. "14:30:45"), `timezone` ("GST (UTC+4)"), and `formatted` (full formatted string, e.g. "2026-03-12 14:30:45 +04"). The agent has a preloaded skill (time-fetcher) that provides the detailed instructions. +- model: haiku + +Wait for the agent to complete and capture the returned time data. + +### Data Contract + +The time-agent MUST return these three fields: +- **time**: The time portion (e.g., "14:30:45") +- **timezone**: "GST (UTC+4)" +- **formatted**: Full formatted string (e.g., "2026-03-12 14:30:45 +04") + +### Step 2: Create SVG Time Card + +Use the Skill tool to invoke the time-svg-creator skill: +- skill: time-svg-creator +- args: Pass the time data from Step 1 — include `time`, `timezone`, and `formatted` values + +The skill will use the time data from Step 1 (available in the current context) to create the SVG card and write output files. + +## Critical Requirements + +1. **Use Agent Tool for time-agent**: DO NOT use bash commands to invoke agents. You must use the Agent tool with `subagent_type: "time-agent"`. +2. **Use Skill Tool for SVG Creator**: Invoke the SVG creator via the Skill tool with `skill: "time-svg-creator"`, not the Agent tool. +3. **Sequential Flow**: The agent MUST complete and return time data before the skill is invoked. Do not run them in parallel. +4. **Data Passing**: Ensure all three fields (time, timezone, formatted) from the agent response are available in context when invoking the skill. + +## Output Summary + +After both steps complete, provide a clear summary to the user showing: +- Current Dubai time fetched +- Timezone: GST (UTC+4) +- Full formatted timestamp +- SVG card created at `agent-teams/output/dubai-time.svg` +- Summary written to `agent-teams/output/output.md` diff --git a/agent-teams/.claude/skills/time-fetcher/SKILL.md b/agent-teams/.claude/skills/time-fetcher/SKILL.md new file mode 100644 index 0000000..3dffa96 --- /dev/null +++ b/agent-teams/.claude/skills/time-fetcher/SKILL.md @@ -0,0 +1,31 @@ +--- +name: time-fetcher +description: Instructions for fetching current Dubai time via bash command +user-invocable: false +--- + +## Dubai Time Fetcher + +### Command + +```bash +TZ='Asia/Dubai' date '+%Y-%m-%d %H:%M:%S %Z' +``` + +### Expected Output Format + +`YYYY-MM-DD HH:MM:SS +04` (Gulf Standard Time) + +### Timezone Details + +- Timezone: Asia/Dubai +- Offset: UTC+4 +- Abbreviation: GST (Gulf Standard Time) +- Dubai does not observe daylight saving time + +### Return Format + +Provide the following fields: +- `time`: Just the time portion (HH:MM:SS) +- `timezone`: "GST (UTC+4)" +- `formatted`: The full output string from the command diff --git a/agent-teams/.claude/skills/time-svg-creator/SKILL.md b/agent-teams/.claude/skills/time-svg-creator/SKILL.md new file mode 100644 index 0000000..b6dbe6c --- /dev/null +++ b/agent-teams/.claude/skills/time-svg-creator/SKILL.md @@ -0,0 +1,30 @@ +--- +name: time-svg-creator +description: Creates an SVG time card showing the current time for Dubai. Writes the SVG to agent-teams/output/dubai-time.svg and updates agent-teams/output/output.md. +allowed-tools: Write, Read +--- + +# Time SVG Creator Skill + +Creates a visual SVG time card for Dubai, UAE and writes the output files. + +## Task + +You will receive three fields from the calling context: `time`, `timezone`, and `formatted`. Create an SVG time card and write both the SVG and a markdown summary. + +## Instructions + +1. **Create SVG** — Use the SVG template from [reference.md](reference.md), replacing placeholders with actual values +2. **Write SVG file** — Write to `agent-teams/output/dubai-time.svg` +3. **Write summary** — Write to `agent-teams/output/output.md` using the markdown template from [reference.md](reference.md) + +## Rules + +- Use the EXACT time values provided — NEVER re-fetch or recalculate +- The SVG must be self-contained and valid +- Both output files go in the `agent-teams/output/` directory + +## Additional resources + +- For SVG template, output template, and design specs, see [reference.md](reference.md) +- For example input/output pairs, see [examples.md](examples.md) diff --git a/agent-teams/.claude/skills/time-svg-creator/examples.md b/agent-teams/.claude/skills/time-svg-creator/examples.md new file mode 100644 index 0000000..c897e6b --- /dev/null +++ b/agent-teams/.claude/skills/time-svg-creator/examples.md @@ -0,0 +1,89 @@ +# Time SVG Creator — Examples + +## Example 1: Afternoon + +### Input + +``` +time: 14:30:45 +timezone: GST (UTC+4) +formatted: 2026-03-12 14:30:45 +04 +``` + +### SVG Output (`agent-teams/output/dubai-time.svg`) + +```svg + + + + + + + + + Dubai Time + 14:30:45 + GST (UTC+4) + Dubai, UAE + 2026-03-12 + +``` + +### Markdown Output (`agent-teams/output/output.md`) + +```markdown +# Dubai Time Card + +- **Time**: 14:30:45 +- **Timezone**: GST (UTC+4) +- **Date**: 2026-03-12 +- **Full**: 2026-03-12 14:30:45 +04 +- **SVG**: `agent-teams/output/dubai-time.svg` + +Generated by time-svg-creator skill. +``` + +--- + +## Example 2: Morning + +### Input + +``` +time: 08:15:02 +timezone: GST (UTC+4) +formatted: 2026-03-12 08:15:02 +04 +``` + +### SVG Output (`agent-teams/output/dubai-time.svg`) + +```svg + + + + + + + + + Dubai Time + 08:15:02 + GST (UTC+4) + Dubai, UAE + 2026-03-12 + +``` + +### Markdown Output (`agent-teams/output/output.md`) + +```markdown +# Dubai Time Card + +- **Time**: 08:15:02 +- **Timezone**: GST (UTC+4) +- **Date**: 2026-03-12 +- **Full**: 2026-03-12 08:15:02 +04 +- **SVG**: `agent-teams/output/dubai-time.svg` + +Generated by time-svg-creator skill. +``` diff --git a/agent-teams/.claude/skills/time-svg-creator/reference.md b/agent-teams/.claude/skills/time-svg-creator/reference.md new file mode 100644 index 0000000..348e19f --- /dev/null +++ b/agent-teams/.claude/skills/time-svg-creator/reference.md @@ -0,0 +1,69 @@ +# Time SVG Creator — Reference + +## SVG Template + +```svg + + + + + + + + + Dubai Time + {{TIME}} + {{TIMEZONE}} + Dubai, UAE + {{DATE}} + +``` + +### Placeholders + +| Placeholder | Replace with | Example | +|-------------|-------------|---------| +| `{{TIME}}` | The `time` value from input | `14:30:45` | +| `{{TIMEZONE}}` | The `timezone` value from input | `GST (UTC+4)` | +| `{{DATE}}` | Date extracted from `formatted` (first 10 chars) | `2026-03-12` | +| `{{FORMATTED}}` | The full `formatted` string (used in markdown only) | `2026-03-12 14:30:45 +04` | + +### Design Specs + +| Property | Value | +|----------|-------| +| Dimensions | 400 x 250 px | +| Corner radius | 16 px | +| Background | Linear gradient: `#0a1628` → `#1a2744` (deep navy to dark blue) | +| Title | `#8892b0` (muted blue), 16px semibold | +| Time display | `#ffffff` (white), 52px bold | +| Timezone | `#64ffda` (teal accent), 16px | +| Location | `#ccd6f6` (light blue), 14px | +| Date | `#8892b0` (muted blue), 12px | +| Font | `sans-serif` | +| All text | Centered (`text-anchor="middle"` at x=200) | + +--- + +## Output Markdown Template + +```markdown +# Dubai Time Card + +- **Time**: {{TIME}} +- **Timezone**: {{TIMEZONE}} +- **Date**: {{DATE}} +- **Full**: {{FORMATTED}} +- **SVG**: `agent-teams/output/dubai-time.svg` + +Generated by time-svg-creator skill. +``` + +--- + +## Output Paths + +| File | Path | +|------|------| +| SVG card | `agent-teams/output/dubai-time.svg` | +| Markdown summary | `agent-teams/output/output.md` | diff --git a/agent-teams/agent-teams-prompt.md b/agent-teams/agent-teams-prompt.md new file mode 100644 index 0000000..dedcc57 --- /dev/null +++ b/agent-teams/agent-teams-prompt.md @@ -0,0 +1,60 @@ +Create an agent team to build a time orchestration workflow that displays +the current Dubai time as a visual SVG card. The workflow follows the +Command → Agent → Skill architecture pattern: + +- A command orchestrates the flow and handles user interaction +- An agent fetches the live current time for Dubai using a preloaded skill +- A skill creates a visual SVG time card from the fetched data + +**Important**: All files must be created inside `agent-teams/.claude/` — +NOT in the repo root's `.claude/` directory. This keeps the agent team's +output self-contained and runnable via `cd agent-teams && claude`. +Do NOT reference or copy the existing weather workflow — build everything from scratch. + +Assign these teammates: + +1. **Command Architect** — Design and implement the `/time-orchestrator` + command in `agent-teams/.claude/commands/time-orchestrator.md`. The command should: + - Invoke the time-agent via the Agent tool (NOT bash) to fetch the + current time for Dubai, UAE (Asia/Dubai timezone, UTC+4) + - Invoke the time-svg-creator skill via the Skill tool to render the + SVG card from the fetched time data + - Use model: haiku in the frontmatter + - Include critical requirements: sequential flow, correct tool usage + (Agent tool for agents, Skill tool for skills), and an output summary + Coordinate with the other teammates via the shared task list to agree + on the data contract ({time, timezone, formatted}) passed between components. + +2. **Agent Engineer** — Design and implement the `time-agent` in + `agent-teams/.claude/agents/time-agent.md` and its preloaded `time-fetcher` + skill in `agent-teams/.claude/skills/time-fetcher/SKILL.md`. The agent should: + - Fetch the current time for Dubai (Asia/Dubai, UTC+4) using Bash + with `TZ='Asia/Dubai' date '+%Y-%m-%d %H:%M:%S %Z'` + - Return the time value, timezone name, and formatted string to the command + - Use frontmatter: tools (Bash), model: haiku, color: blue, maxTurns: 3 + - Preload the time-fetcher skill via the `skills:` field + The time-fetcher skill (`agent-teams/.claude/skills/time-fetcher/SKILL.md`) + should contain the bash command for Dubai time, the expected output format, + and set user-invocable: false since it is agent-only domain knowledge. + Post the agreed data contract to the shared task list so the Command + Architect and Skill Designer can align on the interface. + +3. **Skill Designer** — Design and implement the `time-svg-creator` + skill in `agent-teams/.claude/skills/time-svg-creator/SKILL.md` with supporting + files `reference.md` (SVG template + output template) and `examples.md` + (example input/output pairs). The skill should: + - Receive a time value, timezone, and formatted string from the calling context + - Create a self-contained SVG time card for Dubai showing the current time + - Write the SVG to `agent-teams/output/dubai-time.svg` + - Write a markdown summary to `agent-teams/output/output.md` + - Use the exact time provided — never re-fetch + - Keep templates in reference.md (SVG markup with placeholders, markdown + output template) and example pairs in examples.md + Also create the `agent-teams/output/` directory for the output files. + +All three teammates should create tasks in the shared task list to +coordinate the data contract: the agent returns {time, timezone, formatted}, +the command passes it through context, and the skill consumes it. +Start all three in parallel since the components are independent — +they only need to agree on the data interface, not wait on each other's +implementation. diff --git a/agent-teams/output/dubai-time.svg b/agent-teams/output/dubai-time.svg new file mode 100644 index 0000000..fd01ff5 --- /dev/null +++ b/agent-teams/output/dubai-time.svg @@ -0,0 +1,14 @@ + + + + + + + + + Dubai Time + 17:24:20 + GST (UTC+4) + Dubai, UAE + 2026-03-12 + \ No newline at end of file diff --git a/agent-teams/output/output.md b/agent-teams/output/output.md new file mode 100644 index 0000000..b01bdd5 --- /dev/null +++ b/agent-teams/output/output.md @@ -0,0 +1,9 @@ +# Dubai Time Card + +- **Time**: 17:24:20 +- **Timezone**: GST (UTC+4) +- **Date**: 2026-03-12 +- **Full**: 2026-03-12 17:24:20 +0400 +- **SVG**: `agent-teams/output/dubai-time.svg` + +Generated by time-svg-creator skill. \ No newline at end of file diff --git a/implementation/assets/impl-agent-teams.png b/implementation/assets/impl-agent-teams.png index 61be2ab..e82bf4e 100644 Binary files a/implementation/assets/impl-agent-teams.png and b/implementation/assets/impl-agent-teams.png differ diff --git a/implementation/claude-agent-teams-implementation.md b/implementation/claude-agent-teams-implementation.md index 885e67c..959fad3 100644 --- a/implementation/claude-agent-teams-implementation.md +++ b/implementation/claude-agent-teams-implementation.md @@ -11,7 +11,7 @@ --- -Implemented +Implemented

Agent Teams in action — split pane mode with tmux @@ -23,15 +23,22 @@ Agent Teams spawn **multiple independent Claude Code sessions** that coordinate ## ![How to Use](../!/tags/how-to-use.svg) +The time orchestration workflow was built entirely by an agent team. To run the finished product: + ```bash -tmux new -s oishii -CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude +cd agent-teams +claude +/time-orchestrator ``` +This invokes the **Command → Agent → Skill** pipeline: the agent fetches Dubai's current time, and the skill renders an SVG time card to `agent-teams/output/dubai-time.svg`. + --- ## ![How to Implement](../!/tags/how-to-implement.svg) +You can create a replica of the weather orchestration workflow using agent teams — in this example, the time orchestration workflow was built entirely by an agent team. + ### 1. Install [iTerm2](https://iterm2.com/) and tmux ```bash @@ -48,89 +55,49 @@ CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude ### 3. Prompt with team structure - + -```text -Create an agent team to build "Oishii" — an Asian fine dining restaurant -discovery app. The app lets users browse curated Asian fine dining restaurants, -filter by cuisine (Japanese, Chinese, Thai, Korean, Vietnamese, Indian), -view chef profiles, read tasting menu details, and make reservations. +Paste this prompt into Claude to bootstrap a complete time orchestrator workflow using agent teams: -Assign these teammates: - -1. **Product Manager** — Define the MVP scope, write user stories for the - core flows (browse restaurants, filter by cuisine, view restaurant detail, - make a reservation). Create a product spec in docs/product-spec.md with - acceptance criteria for each story. Coordinate with other teammates via - the shared task list to unblock them. - -2. **Senior Backend Engineer (API)** — Design and implement the REST API - using Node.js/Express with TypeScript. Create the data models - (Restaurant, Chef, Menu, Reservation), seed data with 12 curated Asian - fine dining restaurants across 6 cuisines, and implement endpoints: - GET /restaurants (with cuisine filter), GET /restaurants/:id, - POST /reservations. Write the API in src/api/. - -3. **Senior Backend Engineer (Database)** — Set up the SQLite database - schema with Drizzle ORM. Create migrations, define relations between - tables, and implement the repository layer in src/db/. Coordinate with - the API engineer via tasks to agree on the data model interface. - -4. **Frontend Engineer** — Build the React frontend with Tailwind CSS in - src/app/. Create pages: restaurant listing with cuisine filter chips, - restaurant detail with chef bio and tasting menu, and a reservation - form modal. Use elegant typography and a dark theme befitting fine dining. - Consume the API endpoints defined by the backend team. - -5. **Deployment Engineer** — Set up the project scaffolding (package.json, - tsconfig, vite config), Docker Compose for local dev (app + db), - and a GitHub Actions CI pipeline (.github/workflows/ci.yml) that runs - lint, typecheck, and tests. Write a README.md with setup instructions. - -6. **QA Engineer** — Write end-to-end tests using Vitest for the API - (test all endpoints, edge cases like invalid cuisine filter, double - booking same time slot) and component tests for the React frontend. - Create a test plan in docs/test-plan.md. Run the test suite and - report failures to the team via tasks. - -Each teammate should create tasks in the shared task list to coordinate -dependencies (e.g., Backend DB must finish schema before API can seed data, -API must be running before Frontend can integrate, QA needs both running -before e2e tests). Start with Product Manager and Deployment Engineer -in parallel, then fan out to the rest. -``` +Main prompt: **[agent-teams-prompt.md](../agent-teams/agent-teams-prompt.md)** ### Team Coordination Flow ``` -┌─────────────────────────────────────────────────────────────┐ -│ LEAD (You) │ -│ "Create an agent team to build Oishii..." │ -└──────────────────────────┬──────────────────────────────────┘ - │ spawns team - ┌────────────┴────────────┐ - ▼ ▼ - ┌─────────────────┐ ┌──────────────────┐ - │ Product Manager │ │ Deployment Eng. │ - │ docs/spec.md │ │ scaffolding, │ - │ user stories │ │ Docker, CI │ - └────────┬────────┘ └────────┬─────────┘ - │ tasks: stories ready │ tasks: project ready - ▼ ▼ - ┌──────────────────────────────────────────┐ - │ Shared Task List │ - │ ☐ Schema defined (DB → API) │ - │ ☐ Seed data loaded (API) │ - │ ☐ API endpoints live (API → FE) │ - │ ☐ UI components done (FE → QA) │ - └──────────────────────────────────────────┘ - │ │ - ┌─────────┴──────┐ ┌────────┴────────┐ - ▼ ▼ ▼ ▼ -┌──────────┐ ┌──────────┐ ┌────────────┐ ┌────────┐ -│ Backend │ │ Backend │ │ Frontend │ │ QA │ -│ (DB) │ │ (API) │ │ Engineer │ │Engineer│ -│ src/db/ │ │ src/api/ │ │ src/app/ │ │ tests/ │ -└──────────┘ └──────────┘ └────────────┘ └────────┘ +┌──────────────────────────────────────────────────────────────┐ +│ LEAD (You) │ +│ "Create an agent team to build time orchestration" │ +└──────────────────────────┬───────────────────────────────────┘ + │ spawns team (all parallel) + ┌────────────┼────────────┐ + ▼ ▼ ▼ + ┌────────────────┐ ┌──────────┐ ┌──────────────┐ + │ Command │ │ Agent │ │ Skill │ + │ Architect │ │ Engineer │ │ Designer │ + │ │ │ │ │ │ + │ agent-teams/ │ │ agent- │ │ agent-teams/ │ + │ .claude/ │ │ teams/ │ │ .claude/ │ + │ commands/ │ │ .claude/ │ │ skills/ │ + │ time- │ │ agents/ │ │ time-svg- │ + │ orchestrator.md│ │ time- │ │ creator/ │ + │ │ │ agent.md │ │ │ + └───────┬────────┘ └────┬─────┘ └──────┬───────┘ + │ │ │ + ▼ ▼ ▼ + ┌──────────────────────────────────────────────────┐ + │ Shared Task List │ + │ ☐ Agree on data contract: {time, tz, formatted} │ + │ ☐ Command uses Agent tool (not bash) │ + │ ☐ Agent preloads time-fetcher skill │ + │ ☐ Skill reads time from context (no re-fetch) │ + │ ☐ All files inside agent-teams/.claude/ │ + └──────────────────────────────────────────────────┘ + │ + ▼ + ┌──────────────────────────────┐ + │ cd agent-teams && claude │ + │ /time-orchestrator │ + │ Command → Agent → Skill │ + └──────────────────────────────┘ ```