mano-afk#

Fully automated pipeline that builds, deploys, and tests applications from a natural language description. The user is AFK for the entire duration. The skill learns from each project — build rules and user preferences persist across sessions, so output quality and alignment with the user's taste improve over time.

Claude Code users: Use the Claude Code-specific SKILL.md at claude/SKILL.md.

Architecture#

Three roles collaborate to deliver the application:

• Main Agent (you): orchestration, test execution, fix coordination, user communication
• Build Sub-agent: requirements → architecture → code → deploy → bug fixes (when given specific errors)
• Adversary Sub-agent: independent test case design (does not execute tests)

The main agent delegates code generation to a sub-agent (the longest phase) and stays free during that time. The main agent runs all tests directly for full visibility into results.

Orchestration#

AFK rule: Step 0 is the only user interaction window. From Step 1 onward, make all decisions autonomously — never ask the user. Ambiguous decisions (8bit vs float, React vs Vue, port selection) use the most reasonable default and document in PRD.md. Only stop if completely infeasible (missing hardware, no permissions, 10 fix iterations exhausted).

Step 0: User Setup (interactive)#

This is the only step where the agent may ask the user questions.

Requirements triage: If the request is too vague to determine core functionality (e.g., "build me an app"), or contains ambiguous requirements that could lead to fundamentally different products, ask the user to clarify — keep it to 1-2 focused questions, not a long interview. Non-critical gaps (visual design, validation rules, tech stack, layout) are filled autonomously by the build sub-agent.

E2E test setup: Check mano-afk config --get e2e-mode.

• local or cloud — already configured, proceed.
• Not set — recommend E2E testing to the user: "E2E testing lets mano-afk verify your app through the actual UI — clicking buttons, filling forms, checking visual results. Want to set it up?" Then run mano-afk check and follow its printed guidance to complete configuration. If the user declines, skip E2E — the skill works without it.

When Step 0 completes, tell the user: "Hold the beer. AFK from now on."

Step 1: Prepare (autonomous — no user interaction)#

Derive a short, kebab-case project name from the request (e.g., "make me a todo app" → todo-app).

Project directory: Read the configured project root via mano-afk config --get projects-dir (default: ~/Projects/). Project directory: {projects-dir}/{project-name}/.

Read references/report-template.md — you will use it in Step 4 to write report.md. Note the absolute path to the references/ directory — it will be passed to sub-agents for the remaining reference files.

Step 2: Build (sub-agent)#

Spawn a build sub-agent via sessions_spawn with runtime="subagent". Construct the prompt with:

1. The absolute path to build-pipeline.md — instruct the sub-agent to read and follow it
2. The absolute path to this skill's references/ directory — the sub-agent reads rules.md, preferences.md, and templates as needed
3. The user's original request, verbatim
4. The project directory path

Respond to the user immediately with what is being built and the project directory. The build sub-agent follows 4 phases internally: Phase 1 generates PRD.md (product requirements with acceptance criteria), Phase 2 designs architecture and generates README.md (with test cases derived from PRD), Phase 3 writes code, Phase 4 deploys. Wait for progress.md to show status: ready_for_testing.

Timeout: Build tasks (dependency installation, compilation, deployment) can take a long time. Set a generous timeout when spawning the sub-agent — at least 30 minutes, or no timeout if the platform supports it.

Step 3: Verify Deployment#

Before testing, confirm the app is accessible:

1. Check that deploy/start.sh exists in the project
2. Run it if servers are not already running
3. Verify with curl or port check
4. If deployment fails (start.sh missing, server crashes, port unreachable), read deploy/backend.log and deploy/frontend.log, then go to Step 5 (Fix Loop) with the deployment error as the failure description

Step 4: Test#

Execute every test case defined in the README across all categories. No test case may be skipped or deferred.

Before starting each category, count the total test cases from the README. Print a progress counter for each test: [3/18] api_3 PASS or [5/18] api_5 FAIL. This makes skipped tests visible — if the counter jumps from 3 to 7, tests 4-6 were skipped.

Record results in report.md (use the report template). On failure, include full error output (response body, stderr, logs).

4.1 Lint

Run the linter configured by the build sub-agent. Auto-fix what's possible ( --fix), then report remaining errors.

4.2 API Tests

Run every API test case defined in the README. Use curl -s -w "\nHTTP_STATUS:%{http_code}\n" to capture response body and status code. Print full response body on failure.

4.3 E2E Tests (optional)

E2E tests use mano-afk run to open the app in a browser, interact with the UI via a vision-language model, and verify visual outcomes.

Prerequisites — skip this section entirely if any check fails:

1. mano-afk is on PATH (installed via the skill's brew metadata during skill installation — do NOT install packages autonomously)
2. mano-afk config --get e2e-mode returns local or cloud (if not set, skip and record reason in report.md)

Database reset: Before running the first E2E test, clear all application tables (e.g., DELETE FROM each app table, or delete and re-initialize the SQLite file). This removes residual data from API tests. Do NOT reset between individual E2E tests — they run sequentially and may depend on state created by prior tests.

Run every E2E test case defined in the README:

bash

mano-afk run "{steps}" --url "{url}" --expect "{expected}"

--url opens the target page in the default browser before the agent starts. The agent sees the page already loaded — do NOT include "Open localhost:..." in the task steps.

All execution parameters ( --local/ --cloud, --max-steps, --minimize) are read from mano-afk config. CLI flags override config when specified. Use mano-afk config --list to see current values.

Execution rules:

• Run each test sequentially
• Each mano-afk task can take up to 30 minutes. Set exec timeout to at least 1800s, or use background: true with yieldMs: 1800000. Never use a short timeout
• Do not use mouse/keyboard while a test is running
• Use mano-afk stop to: resolve 409 session conflicts, clean up after a killed process, or abort a running task

4.4 Adversary Review

After all previous tests pass, spawn an adversary sub-agent via sessions_spawn with runtime="subagent". Construct the prompt with:

1. Role: "You are an independent QA reviewer. Your job is to identify potential problems the builder likely missed."
2. The full content of the project's PRD.md (requirements and acceptance criteria) and README.md (architecture and test cases)
3. The project directory path (the adversary reads source code for code-level findings)

The adversary does NOT interact with the running app — it reviews requirements and code only.

The adversary sub-agent identifies potential problems only — it does NOT execute anything. It returns findings in two layers, each as a table with columns: ID, Finding, Severity, Suggested Verification.

• Layer 1 — User perspective: usability gaps, cross-feature consistency, confusing flows, poor UX
• Layer 2 — Code perspective: data integrity, missing validation, error handling, state consistency

Constraints: cover both layers, do NOT repeat issues already in README test cases, do NOT flag security vulnerabilities (XSS, SQL injection, CSRF).

Triage each finding yourself using the appropriate method: code inspection (schema/config issues), API test (backend behavior via curl), or E2E test (UI rendering, user flows, visual state). At least 2-3 findings must be verified via E2E test. Reset the database before running adversary E2E verifications to avoid pollution from prior tests. Record each verdict in report.md: confirmed (→ fix loop) or dismissed (with reason).

Completion Checklist (before proceeding to Step 5 or 6)#

Before moving forward, verify each item. If any is "no", go back and complete it.

• Every API test case in README executed and recorded
• Every E2E test case in README executed and recorded (or all skipped with reason if prerequisites not met)
• Adversary review completed with findings from both layers
• At least 2-3 adversary findings verified via E2E test (if E2E is available)
• All confirmed adversary findings entered into fix loop

Step 5: Fix Loop#

If any test fails:

1. Collect all failures with full error output (response body, stderr, logs, mano-afk output)

2. Spawn a new build sub-agent in fix mode via sessions_spawn with runtime="subagent" — provide:

   • The absolute path to build-pipeline.md (fix mode does not need other reference files)
   • Project directory path
   • Detailed failure descriptions: test ID, command run, expected result, actual result, full error output

3. Wait for the sub-agent to fix and re-deploy ( progress.md shows status: ready_for_testing)

4. Re-run failed tests with the same tool and method used in the original test. A test verified via E2E test must be re-verified via E2E test.

5. Repeat until all pass (max 10 iterations)

E2E false positives: If an E2E test fails but you inspect the code and confirm the implementation is correct (the failure is a vision model misinterpretation), dismiss it as a false positive in report.md with your reasoning. Do not enter the fix loop for false positives — fixing correct code wastes iterations.

Step back on repeated failures: If the same test fails 2+ times, include a note in the fix prompt: "This test has failed N times. Previous fix attempts: [descriptions]. Consider a structural fix rather than a patch."

Exhausted iterations: If 10 iterations are reached and failures remain, proceed to Step 6 with current results. Finalize report.md with all remaining failures, iteration history, and a summary of what was attempted.

Step 6: Completion#

• Summarize to the user: total tests, pass/fail, project directory
• Update rules: Review the fix loop history. If any error pattern would prevent the same class of bug in a future project, add a general rule to references/rules.md (max 100, remove least valuable if full). Also merge any new-rules.md the build sub-agent wrote in the project root.
• Update preferences: If the user gives follow-up feedback (styling, features), update references/preferences.md

Reference Directory#

The references/ directory is local to this skill and contains files that evolve across projects. It does not modify any global CLI configuration, system settings, or files outside this skill's directory.

Scope: These files are only read by mano-afk's build and adversary sub-agents. They have no effect on other skills, other CLI tools, or the host system.

What is stored:

FilePurposeUpdated WhenMax entriesbuild-pipeline.mdBuild sub-agent instructions (phases 1-4 + fix mode)Manual only—rules.mdGeneral build rules, lessons learned from past fix loopsAfter fix loop completes (Step 6)100preferences.mdUser styling/UX preferencesAfter user gives feedback (Step 6)50prd-template.mdPRD generation template (5 chapters)Manual only—project-structure.mdStandard directory layout templateManual only—readme-template.mdREADME.md generation templateManual only—report-template.mdreport.md generation templateManual only—

Only rules.md and preferences.md are modified during execution. All other files are read-only templates. Rules and preferences persist across projects so the skill can improve over time.

Data & Privacy#

• Local by default: Code generation, linting, API tests, and deployment run entirely on your machine.
• Cloud data transmission: E2E tests (4.3) in cloud mode use mano-afk run, which sends screenshots and task descriptions to cloud VLA model providers. This only happens when e2e-mode is explicitly set to cloud via mano-afk config. Local mode and skipping E2E tests involve no cloud calls.
• Opt-in only: E2E tests require explicit configuration ( mano-afk config --set e2e-mode local|cloud). Without this, they are skipped.
• No other external calls: The skill does not phone home, collect telemetry, or send project data to any service beyond the above opt-in test execution.