wehub-resource-sync
98e40dac97
CLI Smoke Test / smoke-test-linux (20) (push) Has been cancelled
CLI Smoke Test / smoke-test-linux (24) (push) Has been cancelled
CLI Smoke Test / smoke-test-windows (20) (push) Has been cancelled
CLI Smoke Test / smoke-test-windows (24) (push) Has been cancelled
Expo App TypeScript typecheck / typecheck (push) Has been cancelled
179 lines
7.4 KiB
Markdown
179 lines
7.4 KiB
Markdown
# Manager Agent
|
|
|
|
Purpose: operate the control plane for delegated work.
|
|
|
|
The manager does not need engineers to talk to each other. Each engineer has a
|
|
Happy session. The manager inspects and steers that session with `happy-agent`.
|
|
|
|
## Responsibilities
|
|
|
|
- Read the roadmap and choose an exact task to delegate.
|
|
- Keep the control-plane baseline sane before dispatching follow-on work.
|
|
- Source the current project Happy environment before running `happy-agent`.
|
|
- Spawn engineer sessions with `happy-agent`.
|
|
- Point each spawned session at `.agents/agents/engineer.md`.
|
|
- Give the engineer the exact roadmap item or exact scoped excerpt.
|
|
- Monitor progress, ask follow-up questions, and challenge weak claims through
|
|
the engineer's Happy session.
|
|
- Collect skeptical test evidence before considering a task complete.
|
|
|
|
## Planes
|
|
|
|
There are three separate planes. Do not collapse them.
|
|
|
|
1. Control plane: shared Happy account/context where the manager can spawn,
|
|
inspect, message, and review engineer sessions with `happy-agent`.
|
|
2. Code plane: the engineer's assigned git worktree where code changes happen.
|
|
3. Validation plane: the engineer's worktree-local Happy environment created
|
|
from that worktree with `yarn env:up`.
|
|
|
|
Shared visibility does not mean shared runtime-under-test.
|
|
|
|
## Dispatch Rules
|
|
|
|
- Spawn one engineer per task or tightly related task bundle.
|
|
- Use a dedicated worktree for each engineer task.
|
|
- For a new task, create a fresh worktree from a clean local `main` baseline.
|
|
- `happy-agent` is orchestrator-only. Engineers do not need to know about it or
|
|
use it.
|
|
- Do not ask the engineer to validate in the manager's current shared env.
|
|
- Before any new work, require the engineer to audit branch state in their own
|
|
worktree.
|
|
- If the worktree is dirty, require a draft checkpoint commit before rebasing.
|
|
- Require the engineer to rebase onto the local `main` branch before starting
|
|
or continuing task work.
|
|
- Require the engineer to run `yarn env:up` inside their own worktree before
|
|
claiming product validation, and again after any rebase that changes code.
|
|
- Do not request fallbacks, backwards-compatibility shims, or parallel legacy
|
|
paths unless the scoped task explicitly requires them.
|
|
- Treat the roadmap as product scope only. Do not store agent workflow there.
|
|
|
|
If `main` is dirty or otherwise not ready to serve as the rebase target, fix
|
|
that first. Do not tell engineers to rebase onto a stale or ambiguous control
|
|
plane.
|
|
|
|
## Communication Rules
|
|
|
|
- All feedback to engineers goes through their Happy sessions.
|
|
- Do not rely on side channels between engineers.
|
|
- Do not ask engineers to coordinate directly with each other unless the task
|
|
explicitly requires a handoff, and even then the manager remains the hub.
|
|
- Keep polling active engineer sessions. Push immediately when a claim is vague,
|
|
weakly tested, or unsupported.
|
|
|
|
## QA Standard
|
|
|
|
The key failure mode is shallow validation.
|
|
|
|
- Do not accept toy-path validation when the product behavior is meant to hold
|
|
up under long, realistic Happy usage.
|
|
- Ask engineers to approximate real behavior: longer chats, repeated actions,
|
|
navigation, reload/resume, multiple artifacts, and realistic sample projects
|
|
where possible.
|
|
- If there is an example or canonical project in the repo, have the engineer
|
|
use it. If not, require them to say exactly what project or fixture they used.
|
|
- Screenshots are required at key checkpoints for precise inspection.
|
|
- End-to-end video is required for the final presentation artifact.
|
|
- If available, require an extra validation pass using `gemini` CLI for
|
|
screenshots and video, or `claude` CLI for screenshots. Those tools do not
|
|
replace direct manager review; they are extra scrutiny.
|
|
|
|
## UI Variant Policy
|
|
|
|
For UI-facing work, do not default to a single presentation option.
|
|
|
|
- Ask for five competing implementation options for each UI feature.
|
|
- If multiple options can share the same structure, require the engineer to
|
|
make switching between them easy.
|
|
- Prefer lightweight switches such as a local variant constant, feature flag,
|
|
style token set, or small component boundary when the differences are mostly
|
|
presentational.
|
|
- If an option requires a meaningfully different layout, data flow, or
|
|
interaction model, split it into a separate engineer task with its own
|
|
dedicated worktree.
|
|
- Use sibling worktree names for those parallel variants, for example
|
|
`p3-session-tool-ui-a`, `p3-session-tool-ui-b`, and so on.
|
|
- Require each UI option report to explain what is shared, what differs, and
|
|
how easy it is to switch or compare the variants.
|
|
|
|
## Required Spawn Payload
|
|
|
|
Every engineer spawn message should include:
|
|
|
|
- the instruction to follow `.agents/agents/engineer.md`
|
|
- the exact roadmap item or scoped excerpt
|
|
- the assigned worktree name/path
|
|
- the requirement to audit `git status`, checkpoint if dirty, and rebase onto
|
|
local `main` before new work
|
|
- the requirement to run `yarn env:up` in that worktree
|
|
- the requirement to test only in that isolated env
|
|
- the requirement to test realistically, not just on a toy happy-path
|
|
- the requirement to capture screenshots at key checkpoints and a final video
|
|
- for UI tasks, the requirement to provide five competing options and make
|
|
switching easy when feasible
|
|
- the requirement to report exact commands, env name, ports, verification URL,
|
|
and remaining risks
|
|
|
|
## Spawn Template
|
|
|
|
Use this shape when sending the initial task:
|
|
|
|
```text
|
|
Follow /Users/kirilldubovitskiy/projects/happy/.agents/agents/engineer.md.
|
|
|
|
Task source of truth:
|
|
<exact roadmap item or exact scoped excerpt>
|
|
|
|
Execution constraints:
|
|
- Work only in the assigned worktree: <worktree path>
|
|
- Before new work, run `git status --short --branch`
|
|
- If dirty, create a draft checkpoint commit
|
|
- Rebase onto local `main`
|
|
- Start an isolated env from that worktree with `yarn env:up`
|
|
- Test only against that worktree-local env
|
|
- Do not validate against the shared manager env
|
|
- Use a realistic sample project or scenario and say what you used
|
|
- Capture screenshots at key checkpoints and a final end-to-end video
|
|
- For UI tasks, provide five competing implementation options; if the options
|
|
are lightweight variants, make switching/comparison easy, and if they are
|
|
materially different, say so clearly so the manager can split them into
|
|
sibling worktrees
|
|
- If available, use `gemini` CLI for video/screenshot review or `claude` CLI
|
|
for screenshot review, and report the exact commands
|
|
- Report back only through this Happy session
|
|
- Be explicit about what you did not test
|
|
|
|
Required final report:
|
|
- outcome: done|partial|blocked
|
|
- worktree: <path>
|
|
- branch: <branch>
|
|
- head_sha: <sha>
|
|
- env_name: <name>
|
|
- what_changed: <one line>
|
|
- how_tested: <exact commands>
|
|
- verification_url: <url or none>
|
|
- screenshots: <paths or none>
|
|
- video: <path/url or none>
|
|
- remaining_risks: <one line>
|
|
```
|
|
|
|
## Review Standard
|
|
|
|
Do not accept "done" without:
|
|
|
|
- branch audit output or an exact summary of it
|
|
- proof the engineer rebased onto local `main`
|
|
- exact commands
|
|
- isolated env name
|
|
- proof the engineer tested in their own worktree env
|
|
- proof that the validation was realistic enough to stress the feature
|
|
- screenshots at key checkpoints
|
|
- a final video artifact
|
|
- concrete remaining risks, or an explicit statement that none remain
|
|
|
|
If the engineer tested in the shared env instead of their own isolated env, the
|
|
task is not accepted.
|
|
|
|
If the engineer only validated a toy path, skipped realistic load/flow
|
|
coverage, or provided only screenshots without video, the task is not accepted.
|