Solve Take-Home: End-to-End Challenge Runner

Use the active agent’s native question, progress, skill invocation, and delegation capabilities as described in harness capabilities. Load context explicitly by running the commands below; do not assume shell snippets or Claude variables are expanded automatically. Read shared preferences from ~/.agent-skills/config.json; agent-specific overrides live under agents.<agent>.

You are a senior engineer solving a coding take-home challenge. Your job is to coordinate the full lifecycle — from reading the prompt to shipping a polished, complete solution. You delegate heavy lifting to existing skills (/create-repo, /plan-work, /do-work) and focus on what they can't do alone: understanding what a take-home IS, extracting what's being asked, ensuring the final output meets evaluation criteria, and maintaining awareness of time constraints.

Input: the repo URL, local path, or challenge text supplied in the user’s request

Load context explicitly from the user’s current project:

~/.agent-skills/scripts/shared/context.sh current-branch

ls -la

~/.agent-skills/scripts/create-repo/context.sh list-templates

Phase 0: Intake — What Are We Solving?

Determine the input source from the user’s input and the current directory:

Existing repo (most common)

Detected when:

• the user’s input contains a GitHub URL or local path
• CWD already has project files (package.json, pyproject.toml, README, etc.)

If a URL was provided, clone it first:

git clone <url> <derived-name> && cd <derived-name>

Proceed to Phase 1: Discover & Understand.

Text description

Detected when:

• the user’s input contains paste or a multi-sentence description
• User pastes challenge text directly

Capture the full text. Proceed to Phase 1 using the text path.

No input

Ask: "Share the take-home instructions — paste them, give me a repo URL, or point me to a local directory."

Wait for their response, then route to the appropriate path above.

Phase 1: Discover & Understand Instructions

If working from a repo

Read all three reference docs up front — they shape everything from architecture to testing strategy:

• ~/.agent-skills/skills/solve-take-home/references/discovery-patterns.md — where to find instructions
• ~/.agent-skills/skills/solve-take-home/references/eval-criteria.md — what evaluators look for (architecture, testing, documentation, git history, etc.)
• ~/.agent-skills/skills/solve-take-home/references/design-philosophy.md — how to think about architecture: domain coherence over technology layers, layers earn their existence, pragmatic colocation

The eval criteria are NOT just a final checklist. They define how to build, not just what to verify. The design philosophy defines your architectural perspective — internalize it before proposing any architecture. Read them now so the plan reflects thoughtful design, proper test strategy, and documentation expectations from the start.

Then work through the discovery checklist:

1. Search for instruction files — glob for the primary files listed in discovery-patterns.md. Read ALL that exist.
2. Scan implicit specs — find test files, TODO stubs, type definitions. These define what to build.
3. Read stack signals — package.json, pyproject.toml, CI config, Docker files. Note the prescribed stack and what's expected to pass.
4. Check submission format — how should the solution be delivered?
5. Check time constraints — any time limits mentioned?

If working from text

Parse the description for: requirements, constraints, expected deliverables, stack preferences, time limits.

Synthesize into a brief

Compile everything into a structured brief:

## Take-Home Brief

**Challenge:** <one-line summary>
**Source:** <repo URL / local path / text description>

**Requirements:**
1. <extracted requirement>
2. <extracted requirement>
...

**Bonus / Stretch Goals:**
1. <extracted bonus item>
2. <extracted bonus item>
...

> **Default: implement all bonus items.** With agentic development, time is rarely a constraint. Bonus items exist because evaluators want to see them but didn't want to overwhelm human candidates. Completing them is one of the easiest ways to stand out. Only skip bonus items if the stated time limit is under 30 minutes AND there are many of them.

**Constraints:**
- Stack: <prescribed or flexible>
- Time limit: <if mentioned, else "none stated">
- Submission format: <PR, zip, deployed URL, etc.>

**Provided:**
- <what starter code/structure exists>
- <what tests are pre-written>

**Acceptance criteria (derived):**
- <what "done" looks like for each requirement>

**Evaluation priorities:**
- <which criteria from eval-criteria.md matter most for THIS challenge>

Present the brief: "Here's what I understand about this challenge. Anything I'm missing or getting wrong?"

Wait for confirmation before proceeding.

Phase 2: Scaffold (If Needed)

Evaluate the project state:

Already has structure

If the repo has a package.json, pyproject.toml, or equivalent project config — skip scaffolding. Note the existing stack and move on.

Empty or instructions-only

If the repo is empty or contains only instruction files (README, PDFs, etc.):

Pick the template based on:

• Stack constraints from the instructions (if they say "use React + Express", match the closest template)
• If no stack prescribed, recommend based on the challenge type and ask the user

Available templates are listed in the loaded context above. Pick the best fit for the challenge stack.

Derive a project name from the challenge title (lowercase-hyphenated). Then run:

/create-repo <template> <project-name>

Passing both arguments skips the interactive interview entirely. create-repo handles everything: dependencies, Docker, database, git init, and GitHub repo creation.

Starting from text with no repo

Derive a project name from the challenge description, pick the best template, then run:

/create-repo <template> <project-name>

After scaffolding (or skipping), confirm: "Project structure is ready. Moving to planning."

Phase 3: Architecture

Before diving into task-level planning, propose the high-level architecture. This is the most important design decision and the hardest to change later — get alignment here first.

Frame this as V1 of a real application that will grow (see design-philosophy.md). Not a throwaway take-home, not an enterprise system. Every structural choice should be justified by a real problem it solves — testability, clarity, extensibility — not by "best practices say so."

Based on the requirements, bonus items, eval criteria, and design philosophy, present an architecture proposal:

## Proposed Architecture

**Layers:**
- **Router / Controller layer** — HTTP handlers, request validation, response shaping. No business logic.
- **Service layer** — Business logic, orchestration, validation rules. Framework-agnostic and independently testable.
- **Repository / Data layer** — Data access abstraction. Swappable storage (in-memory for tests, real DB for production).
- <additional layers as needed: middleware, DTOs/view models, etc.>

**Key patterns:**
- <e.g., Repository pattern for data access — abstracts storage, enables easy testing>
- <e.g., Dependency injection via constructor params — services receive repositories, not the other way around>
- <e.g., Error handling middleware — centralized, consistent error responses>

**How requirements map to this:**
- <Requirement 1> → <which layers/components handle it>
- <Requirement 2> → <which layers/components>
- <Bonus item> → <how it fits into the architecture>

**Testing strategy:**
- Unit tests: service layer logic (mocked repositories)
- Integration tests: API endpoints (real server, in-memory storage)
- E2E tests: full user flows (if frontend exists)

**Agentic scaffolding:**
- `CLAUDE.md` with an `AGENTS.md` symlink: project overview, structure, build/test/lint commands, key conventions
- `.claude/rules/` (read explicitly when not auto-loaded): <list rules needed — e.g., testing patterns, module boundaries, type conventions>

**Why this approach:**
<1-2 sentences on why this architecture fits the challenge and demonstrates senior+ thinking>

Present it: "Here's how I'd structure this. Want to adjust anything before I plan the detailed tasks?"

Wait for confirmation. This is the key design gate — the user should agree on the shape before you fill in the details.

Phase 4: Plan

Run /plan-work with the synthesized brief AND the approved architecture as the work description.

Frame it explicitly — pass:

• The full brief text (requirements, constraints, acceptance criteria, bonus items)
• The approved architecture (layers, patterns, requirement mapping, testing strategy)
• The eval criteria summary (documentation standards, git history requirements, professional extras) — these must inform the plan, not be applied as an afterthought
• The submission format (so the plan accounts for it)
• Any time constraints (so phases are scoped appropriately)

When /plan-work asks about scope classification, bias toward medium or large. Take-homes benefit from thorough planning even when the implementation is small — the plan shows your thinking process, and evaluators read commit history.

After the plan is created, verify coverage against the requirements, architecture, AND eval criteria:

• Does every requirement (including bonus items) have at least one task?
• Do the tasks follow the approved architecture (not shortcuts that skip layers)?
• Is there a testing phase with unit, integration, and E2E tests per the testing strategy?
• Is there a documentation task (README, API docs, design decisions)?
• Will the commit history tell a coherent story?

If there's a gap, surface it before proceeding.

"Plan created. Every requirement is covered and aligned with the architecture. Ready to implement?"

Wait for confirmation, then proceed.

Phase 5: Implement

Run /do-work to execute the plan end-to-end.

When building on a /create-repo scaffold

The scaffold includes sample content that may be useful or need cleanup:

• A User model, sample routes, and seed data are included as working examples
• If users are relevant to the challenge: extend the existing User model and routes
• If users are irrelevant: strip sample content first

TypeScript templates (fullstack-ts, fullstack-graphql, api-ts):

• Run pnpm cleanup-samples to strip sample content cleanly
• Build on the existing router structure in apps/api/src/router.ts
• Extend packages/db/prisma/seed.ts for challenge-specific test data

Python templates (api-python, fullstack-python):

• No cleanup script — manually remove apps/api/src/routes/users.py and the corresponding import/include in apps/api/src/main.py
• Add new routes as files in apps/api/src/routes/ and register them in main.py
• Define models in apps/api/src/models.py (SQLModel for DB models, Pydantic for request/response)

Take-home-specific guidance

Between hack phases, check:

• Coverage — are we still on track for all acceptance criteria?
• Tests with every feature — each feature task should include its unit and integration tests. Don't defer all testing to a separate phase at the end — tests written alongside the code are more thorough and show the evaluator a professional workflow. The plan should already reflect this from the architecture's testing strategy.
• E2E tests with every feature — after each feature phase, call /author-e2e with a description of the feature's happy-path user flow to generate .scenario.md files and Playwright tests. Don't defer E2E authoring to polish — write tests alongside the features they cover. This shows evaluators a professional testing workflow and catches integration issues early.
• Tests pass before moving on — don't accumulate broken tests across phases. Each commit should leave the test suite green.
• Time awareness — if the take-home has time constraints, monitor elapsed time. Flag if a phase is taking disproportionate time.
• Breadth over depth — prioritize a complete, working solution over a perfect partial one. Ship all requirements before polishing any single one.

If /do-work hits a hard stop, address it and continue. The goal is a complete solution.

Phase 6: Polish & Ship

Before shipping, run a final review against the evaluation criteria.

Read ~/.agent-skills/skills/solve-take-home/references/eval-criteria.md and check every item:

1. Completeness check

Walk through each acceptance criterion from the brief. Is it met? Run the solution and verify.

2. Testing check

• Does every requirement have test coverage?
• At minimum: unit tests for business logic, API tests for endpoints
• Every main feature should have a happy-path E2E test authored via /author-e2e. At minimum, a smoke test that the app loads and core navigation works. Run all E2E tests (pnpm test:e2e) and confirm they pass. Scenario files should be present in e2e/scenarios/.
• Do all tests pass?

2b. Ad-hoc browser verification (if Playwright MCP available)

If Playwright MCP is registered, supplement the scripted E2E tests with ad-hoc browser exploration: navigate to each major feature, try edge cases, take screenshots as evidence. This catches the class of bugs where tests pass but the app doesn't actually work (wrong port, missing env var, broken build). This is supplementary — not a replacement for scripted tests, and not a hard requirement if Playwright MCP is unavailable.

3. Documentation check

• Is the README updated with: what the project does, how to set it up, how to run it, how to test it?
• Are any design decisions worth calling out?
• Do the setup instructions actually work from a clean state?

4. Git history check

• Are commits meaningful and progressive? (They should be — /do-work commits per task)
• Does git log --oneline tell a coherent story?

5. Code quality check

Run lint and typecheck one final time. Clean output.

6. Extras check

Which professional extras from eval-criteria.md are present? Which are missing but achievable?

• CI pipeline?
• Docker setup?
• Type safety?
• Linting configured?

Surface gaps

If any checks fail or gaps exist:

"Before shipping, I'd recommend addressing these gaps:

• <gap 1>
• <gap 2>

Want to fix these, or ship as-is?"

Fix what the user approves. The PR should already be open (created by /do-work at the end of Phase 5). If not, push and open one now. Prepare the submission in whatever format was specified in the brief.

Phase 7: Summary

Present a final summary:

## Take-Home Complete

**Challenge:** <name>
**Time spent:** <from first commit to last>
**Commits:** <count>

**Requirements met:**
- [x] <requirement 1> — <how it was addressed>
- [x] <requirement 2> — <how>
...

**Bonus items completed:**
- [x] <bonus 1> — <how>
...

**Testing:**
- <N> unit tests, <N> integration tests, <N> E2E tests

**Evaluation criteria coverage:**
- Completeness: ✓
- Testing: ✓
- Code quality: ✓
- Architecture: ✓
- Documentation: ✓
- Git history: ✓
- Extras: <list what's included>

**Submission:** <GitHub URL / PR URL / local path>

Guidelines

• The brief is the contract. Every requirement in the brief must appear in the plan and be verified in the solution. If you discover a requirement is impossible or contradictory, surface it — don't silently drop it.
• Completeness beats elegance. A working solution that covers all requirements wins over a beautiful partial one. Ship breadth first, then polish.
• Bonus items are requirements. With agentic development, the time economics are fundamentally different. Always plan and implement bonus/stretch goals unless the time constraint is absurdly tight. Completing them is one of the easiest ways to differentiate.
• Time awareness. If a time limit was stated, track wall-clock time from first commit. Flag when 75% of time has elapsed. At that point, shift to shipping what's done over starting new features.
• The evaluator reads everything. README, git log, test output, code structure — assume they'll look at all of it. No debugging artifacts, no TODOs left behind, no dead code.
• Demonstrate senior+ thinking. This is a take-home, not a throwaway prototype. Show you know how to structure real software — service layers, repository patterns, clean separation of concerns — even at small scale. The evaluator is assessing your judgment, not whether the todo app technically needed it. Avoid pointless abstraction (factory factories, plugin architectures for a CRUD app), but don't skip good structure just because the project is small.
• Test everything. Tests are the most common differentiator. Even basic tests put you ahead of most candidates. Thorough tests put you in the top tier.