Tutorial 3 Your First Agent Task en SG

Tutorial 3 · Your First Agent Task

🌎 Language: Singlish (en-SG) — see all 33 languages

Goal: add a brand-new command to the CLI — end to end — by directing your agent. We'll add lockedin endorse: it endorses total strangers for skills they almost certainly don't have. On brand.

This is the heart of the tutorial. You'll practice the real loop: spec → tests → implementation → green gate → review.

← Prev: Tutorial 2 How the Code Works · Next: Tutorial 4 Prompting and Reviewing

---

Step 0 — Decide what "done" looks like

Before prompting anything, settle the spec yourself first in plain language. Vague requests get vague code — from a human or an agent.

endorse prints 5–7 lines, each endorsing a randomly chosen person (reuse the existing NAMES pool) for a randomly chosen buzzword skill (a new pool). It ends with a satirical one-liner. It must be reachable as lockedin endorse, as the in-session /endorse, and appear in help. All randomness must use the seeded pick/shuffle helpers so output stays deterministic. npm test must stay green, and there should be a new test that pins down at least one invariant.

That paragraph is the thing you'll hand the agent. Notice it names the constraints from Chapter 2 (seeded RNG, the test gate, the invariants habit).

Step 1 — Ask the agent to plan, not code

Start by asking for a plan. This is your chance to catch a bad approach before any files change.

"I want to add an endorse command to LockedIn CLI. Here's the spec: [paste your spec]. Before writing code, tell me which files you'll change and your approach, so I can approve it. Follow the existing patterns for a command like connect."

A good plan mentions: a new SKILLS pool + a renderEndorse() in src/lockedin.js, wiring it into dispatch() and handleSlash(), adding a row to renderHelp(), exporting the new function/pool, and adding tests in both test files. If the plan misses the seeded-RNG rule or the tests, say so now.

Step 2 — Test-first

Ask the agent to write the tests before the implementation. Tests-first turns your spec into something executable, and it keeps the agent honest.

"Great. First, add failing tests only: a unit test that renderEndorse() returns text mentioning a known skill and at least 5 endorsements, and a cli.test.js test that lockedin endorse exits 0 and prints an endorsement. Use a fixed seed. Don't implement renderEndorse yet — let's see the tests fail first."

Run them and watch them fail for the right reason (the function doesn't exist yet):

npm test

Step 3 — Let the agent implement

Now green-light the implementation:

"Now implement it to make those tests pass, following the connect pattern. Add a SKILLS pool of ~25 buzzword skills, a renderEndorse() that returns a string, wire up dispatch and handleSlash, add a help row, and export what you added. Only use pick/shuffle for randomness."

What the agent produces should look a lot like the rest of the file. For example, a SKILLS pool and a renderer:

const SKILLS = [
  'Thought Leadership', 'Synergy', 'Storytelling', 'Vibes',
  'Strategic Napping', 'Stakeholder Alignment', 'Radical Candour', /* ...~25 total... */
];

function renderEndorse() {
  const people = shuffle(NAMES).slice(0, 5 + Math.floor(rand() * 3)); // 5–7
  const skills = shuffle(SKILLS);
  const out = [''];
  people.forEach((n, i) =>
    out.push('  ✔ Endorsed ' + n + ' for ' + skills[i % skills.length]));
  out.push('', '  You endorsed 6 strangers for skills you cannot verify. Within one hour they confirm endorse you back.');
  return out.join('\n');
}

…plus one line each in dispatch() and handleSlash(), a row in renderHelp(), and SKILLS, renderEndorse added to module.exports.

Step 4 — The gate

npm test

Green? Shiok — you just shipped a feature with an agent, test-first. Not green? That's normal — go to Chapter 4's iteration loop and tell the agent exactly what failed.

Then eyeball the real thing (tests check text, but you should still look):

node bin/lockedin.js endorse
LOCKEDIN_SEED=1 node bin/lockedin.js endorse   # reproducible

Step 5 — Review before you accept

Never anyhow accept a diff you haven't read. Skim for these specifically:

• Did it follow the pattern? New command should mirror connect — no new dependencies, no console.log inside src/.
• Seeded RNG only? Search the diff for Math.random. There should be none.
• Did it touch anything it shouldn't? The change should be additive; unrelated lines shouldn't move.
• Is the new test meaningful? It should fail if someone later breaks the feature — not just assert true.

If anything off, ask for a fix (Chapter 4). If it's good, you're done.

---

✅ Try it with your agent

Do the whole loop above for real. Then, for extra credit, ask the agent to extend it:

• "Make endorse accept an optional name: lockedin endorse Ada should endorse Ada specifically. Add a test, keep the gate green."

You've now built a feature end-to-end. The last chapter is about doing this smoothly — prompting and reviewing like a lead engineer.

Next: Tutorial 4 Prompting and Reviewing