Skip to content

Commit dfe64ab

Browse files
Merge pull request #10 from MLH/feat/hello-world-challenge
feat: add hello-world challenge
2 parents 416906f + d5498a2 commit dfe64ab

9 files changed

Lines changed: 244 additions & 0 deletions

File tree

‎.markdownlint-cli2.jsonc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44
"ignores": [
55
// Its placeholders read as HTML, and it opens without a heading by design.
66
".github/pull_request_template.md",
7+
// The challenge spec bars a title in intro.md; the Intro screen shows it from the manifest.
8+
"*/intro.md",
79
// Fixture Markdown is test data, not documentation.
810
"test/fixtures/**",
911
"**/node_modules/**"

‎hello-world/README.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# hello-world
2+
3+
The 5-minute first challenge. Pi reads a seeded `welcome.txt`, greets the
4+
participant, then creates `hello.txt` containing `Hello, world!`.
5+
6+
## Run it standalone in Pi
7+
8+
The commands follow boothstrap.sh's `docs/authoring-challenges.md`. This
9+
package has no `install` hook, no Pi extensions, and no MCP servers. Export
10+
`GEMINI_API_KEY`, then set the package path:
11+
12+
```sh
13+
challenge=/absolute/path/to/microhackathon-challenges/hello-world
14+
```
15+
16+
Install Pi and the adapter, at the versions boothstrap pins:
17+
18+
```sh
19+
npm install -g @earendil-works/pi-coding-agent@1.0.4
20+
pi install npm:pi-mcp-adapter@5.2.0
21+
```
22+
23+
Load the package by adding its absolute path to `settings.agentPluginPaths` in
24+
`~/.pi/agent/mcp-adapter.json`, or in `$PI_CODING_AGENT_DIR/mcp-adapter.json`:
25+
26+
```json
27+
{
28+
"settings": {
29+
"agentPluginPaths": ["/absolute/path/to/microhackathon-challenges/hello-world"]
30+
}
31+
}
32+
```
33+
34+
Seed a scratch folder, then start Pi in it:
35+
36+
```sh
37+
mkdir /tmp/hello-world-attempt && cd /tmp/hello-world-attempt
38+
"$challenge"/setup
39+
pi --model google/gemini-3.8-flash \
40+
--skill "$challenge"/skills/start-challenge/SKILL.md \
41+
'/skill:start-challenge'
42+
```
43+
44+
Clean up when done:
45+
46+
```sh
47+
"$challenge"/cleanup
48+
```
49+
50+
Without boothstrap there is no `report_step`, so the skill tells the
51+
participant which step they finished instead.

‎hello-world/challenge.json‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
{
2+
"id": "hello-world",
3+
"title": "Hello, World!",
4+
"tagline": "Meet your AI guide and make your first file.",
5+
"type": "terminal",
6+
"agent": "pi",
7+
"model": "google/gemini-3.8-flash",
8+
"vault_services": ["gemini"],
9+
"icon": "prompt",
10+
"points": 50,
11+
"estimated_minutes": 5,
12+
"learning_objectives": ["AI-assisted file creation"],
13+
"featured_tech": ["Pi", "Gemini"],
14+
"intro": "intro.md",
15+
"steps": [
16+
{
17+
"id": "greet",
18+
"title": "Meet your guide",
19+
"hint": "Ask Pi to read welcome.txt and say hello.",
20+
"done_when": "Pi has read welcome.txt in the workspace and greeted the participant."
21+
},
22+
{
23+
"id": "hello-file",
24+
"title": "Make your first file",
25+
"hint": "Ask Pi to create hello.txt with the words Hello, world!",
26+
"done_when": "hello.txt exists in the workspace and contains the text Hello, world!"
27+
}
28+
]
29+
}

‎hello-world/cleanup‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
#!/bin/sh
2+
set -eu
3+
4+
workspace=${BOOTHSTRAP_WORKSPACE:-$PWD}
5+
6+
rm -f -- "$workspace/welcome.txt"

‎hello-world/intro.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Meet Pi, your AI guide. Ask it to read the welcome note, `welcome.txt`, and
2+
say hello. Then ask it to make a small text file, `hello.txt`, that says
3+
`Hello, world!`. No terminal experience needed.
4+
5+
You'll practice giving an agent a clear instruction and checking its work.

‎hello-world/plugin.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
3+
"name": "hello-world",
4+
"version": "1.0.0",
5+
"description": "A two-step introduction to making a file with an AI agent"
6+
}

‎hello-world/setup‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
#!/bin/sh
2+
set -eu
3+
4+
workspace=${BOOTHSTRAP_WORKSPACE:-$PWD}
5+
if [ ! -d "$workspace" ] || [ ! -w "$workspace" ]; then
6+
echo "hello-world setup: workspace is missing or not writable: $workspace" >&2
7+
exit 1
8+
fi
9+
10+
printf 'Hello from the hello-world challenge!\n' > "$workspace/welcome.txt"
Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
name: start-challenge
3+
description: Guide a participant through the Hello, World! booth challenge. Use when starting or resuming this challenge.
4+
---
5+
6+
# Hello, World! guide
7+
8+
Keep the tone warm and beginner-friendly. Work in the current workspace, not
9+
the installed package directory.
10+
11+
1. Invite the participant to ask you to read `welcome.txt` and say hello. When
12+
they do, read the file and greet them, then report step `greet`.
13+
2. Invite them to ask you to make a file. When they do, create `hello.txt` in
14+
the workspace containing `Hello, world!`. Read it back to verify. If the
15+
file already exists, read it first and correct it if it doesn't contain
16+
`Hello, world!`. Only then report step `hello-file`.
17+
18+
To report a step, call `report_step` with its `step_id`. If `report_step`
19+
returns an error, say the portal did not register the step and retry once. If
20+
it still fails, ask booth staff for help and do not claim points were awarded.
21+
22+
If `report_step` is missing, you are running in plain Pi: tell the participant
23+
which step they just finished, and congratulate them after the second. Outside
24+
boothstrap there is no checklist or points.

‎test/hello-world.test.mjs‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
// Proves the hello-world package's manifest invariants and that its setup and
2+
// cleanup hooks behave on a workspace, offline.
3+
4+
import assert from 'node:assert/strict'
5+
import { execFile } from 'node:child_process'
6+
import { mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promises'
7+
import { tmpdir } from 'node:os'
8+
import path from 'node:path'
9+
import { test } from 'node:test'
10+
import { fileURLToPath } from 'node:url'
11+
import { promisify } from 'node:util'
12+
13+
const execFileAsync = promisify(execFile)
14+
const challengeDirectory = fileURLToPath(new URL('../hello-world/', import.meta.url))
15+
16+
/** Creates a temporary directory that is removed when the test ends. */
17+
const makeDirectory = async (context) => {
18+
const directory = await mkdtemp(path.join(tmpdir(), 'hello-world-'))
19+
context.after(() => rm(directory, { recursive: true, force: true }))
20+
21+
return directory
22+
}
23+
24+
/**
25+
* Runs a hook from `cwd` with a clean environment. `BOOTHSTRAP_WORKSPACE` is
26+
* set only when `workspace` is given, so omitting it exercises the standalone
27+
* fallback to the current directory.
28+
*/
29+
const runHook = (hook, { cwd, workspace }) =>
30+
execFileAsync(path.join(challengeDirectory, hook), [], {
31+
cwd,
32+
env: {
33+
PATH: process.env.PATH,
34+
HOME: cwd,
35+
TMPDIR: cwd,
36+
...(workspace === undefined ? {} : { BOOTHSTRAP_WORKSPACE: workspace }),
37+
},
38+
})
39+
40+
/** Reads the package manifest. */
41+
const readManifest = async () => JSON.parse(await readFile(path.join(challengeDirectory, 'challenge.json'), 'utf8'))
42+
43+
/** Lists a directory's entries in a stable order. */
44+
const listSorted = async (directory) => (await readdir(directory)).sort()
45+
46+
test('manifest keeps the step IDs and model the skill depends on', async () => {
47+
const manifest = await readManifest()
48+
49+
assert.deepEqual(manifest.steps.map((step) => step.id), ['greet', 'hello-file'])
50+
assert.equal(manifest.model, 'google/gemini-3.8-flash')
51+
assert.deepEqual(manifest.vault_services, ['gemini'])
52+
})
53+
54+
test('skill names every step the manifest declares', async () => {
55+
const manifest = await readManifest()
56+
const skill = await readFile(path.join(challengeDirectory, 'skills/start-challenge/SKILL.md'), 'utf8')
57+
58+
for (const step of manifest.steps) {
59+
assert.ok(skill.includes(`\`${step.id}\``), `skill never names step ${step.id}`)
60+
}
61+
})
62+
63+
test('setup seeds welcome.txt in the workspace', async (context) => {
64+
const cwd = await makeDirectory(context)
65+
const workspace = await makeDirectory(context)
66+
67+
await runHook('setup', { cwd, workspace })
68+
69+
assert.match(await readFile(path.join(workspace, 'welcome.txt'), 'utf8'), /hello/i)
70+
assert.deepEqual(await listSorted(cwd), [])
71+
})
72+
73+
test('cleanup run twice removes the seeded file and keeps the participant\'s files', async (context) => {
74+
const cwd = await makeDirectory(context)
75+
const workspace = await makeDirectory(context)
76+
await runHook('setup', { cwd, workspace })
77+
await writeFile(path.join(workspace, 'hello.txt'), 'Hello, world!')
78+
79+
await runHook('cleanup', { cwd, workspace })
80+
await runHook('cleanup', { cwd, workspace })
81+
82+
assert.deepEqual(await listSorted(workspace), ['hello.txt'])
83+
assert.equal(await readFile(path.join(workspace, 'hello.txt'), 'utf8'), 'Hello, world!')
84+
})
85+
86+
test('cleanup succeeds after setup failed on a missing workspace', async (context) => {
87+
const cwd = await makeDirectory(context)
88+
const workspace = path.join(cwd, 'never-created')
89+
90+
await assert.rejects(runHook('setup', { cwd, workspace }), /workspace/i)
91+
await runHook('cleanup', { cwd, workspace })
92+
93+
assert.deepEqual(await listSorted(cwd), [])
94+
})
95+
96+
test('setup seeds the current directory when BOOTHSTRAP_WORKSPACE is unset', async (context) => {
97+
const cwd = await makeDirectory(context)
98+
99+
await runHook('setup', { cwd })
100+
101+
assert.match(await readFile(path.join(cwd, 'welcome.txt'), 'utf8'), /hello/i)
102+
})
103+
104+
test('cleanup clears the current directory when BOOTHSTRAP_WORKSPACE is unset', async (context) => {
105+
const cwd = await makeDirectory(context)
106+
await runHook('setup', { cwd })
107+
108+
await runHook('cleanup', { cwd })
109+
110+
assert.deepEqual(await listSorted(cwd), [])
111+
})

0 commit comments

Comments
 (0)