Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .markdownlint-cli2.jsonc
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@
"ignores": [
// Its placeholders read as HTML, and it opens without a heading by design.
".github/pull_request_template.md",
// The challenge spec bars a title in intro.md; the Intro screen shows it from the manifest.
"*/intro.md",
// Fixture Markdown is test data, not documentation.
"test/fixtures/**",
"**/node_modules/**"
Expand Down
51 changes: 51 additions & 0 deletions hello-world/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# hello-world

The 5-minute first challenge. Pi reads a seeded `welcome.txt`, greets the
participant, then creates `hello.txt` containing `Hello, world!`.

## Run it standalone in Pi

The commands follow boothstrap.sh's `docs/authoring-challenges.md`. This
package has no `install` hook, no Pi extensions, and no MCP servers. Export
`GEMINI_API_KEY`, then set the package path:

```sh
challenge=/absolute/path/to/microhackathon-challenges/hello-world
```

Install Pi and the adapter, at the versions boothstrap pins:

```sh
npm install -g @earendil-works/pi-coding-agent@1.0.4
pi install npm:pi-mcp-adapter@5.2.0
```

Load the package by adding its absolute path to `settings.agentPluginPaths` in
`~/.pi/agent/mcp-adapter.json`, or in `$PI_CODING_AGENT_DIR/mcp-adapter.json`:

```json
{
"settings": {
"agentPluginPaths": ["/absolute/path/to/microhackathon-challenges/hello-world"]
}
}
```

Seed a scratch folder, then start Pi in it:

```sh
mkdir /tmp/hello-world-attempt && cd /tmp/hello-world-attempt
"$challenge"/setup
pi --model google/gemini-3.8-flash \
--skill "$challenge"/skills/start-challenge/SKILL.md \
'/skill:start-challenge'
```

Clean up when done:

```sh
"$challenge"/cleanup
```

Without boothstrap there is no `report_step`, so the skill tells the
participant which step they finished instead.
29 changes: 29 additions & 0 deletions hello-world/challenge.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
{
"id": "hello-world",
"title": "Hello, World!",
"tagline": "Meet your AI guide and make your first file.",
"type": "terminal",
"agent": "pi",
"model": "google/gemini-3.8-flash",
"vault_services": ["gemini"],
"icon": "prompt",
"points": 50,
"estimated_minutes": 5,
"learning_objectives": ["AI-assisted file creation"],
"featured_tech": ["Pi", "Gemini"],
"intro": "intro.md",
"steps": [
{
"id": "greet",
"title": "Meet your guide",
"hint": "Ask Pi to read welcome.txt and say hello.",
"done_when": "Pi has read welcome.txt in the workspace and greeted the participant."
},
{
"id": "hello-file",
"title": "Make your first file",
"hint": "Ask Pi to create hello.txt with the words Hello, world!",
"done_when": "hello.txt exists in the workspace and contains the text Hello, world!"
}
]
}
6 changes: 6 additions & 0 deletions hello-world/cleanup
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
#!/bin/sh
set -eu

workspace=${BOOTHSTRAP_WORKSPACE:-$PWD}

rm -f -- "$workspace/welcome.txt"
5 changes: 5 additions & 0 deletions hello-world/intro.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
Meet Pi, your AI guide. Ask it to read the welcome note, `welcome.txt`, and
say hello. Then ask it to make a small text file, `hello.txt`, that says
`Hello, world!`. No terminal experience needed.

You'll practice giving an agent a clear instruction and checking its work.
6 changes: 6 additions & 0 deletions hello-world/plugin.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "hello-world",
"version": "1.0.0",
"description": "A two-step introduction to making a file with an AI agent"
}
10 changes: 10 additions & 0 deletions hello-world/setup
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
#!/bin/sh
set -eu

workspace=${BOOTHSTRAP_WORKSPACE:-$PWD}
if [ ! -d "$workspace" ] || [ ! -w "$workspace" ]; then
echo "hello-world setup: workspace is missing or not writable: $workspace" >&2
exit 1
fi

printf 'Hello from the hello-world challenge!\n' > "$workspace/welcome.txt"
24 changes: 24 additions & 0 deletions hello-world/skills/start-challenge/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
---
name: start-challenge
description: Guide a participant through the Hello, World! booth challenge. Use when starting or resuming this challenge.
---

# Hello, World! guide

Keep the tone warm and beginner-friendly. Work in the current workspace, not
the installed package directory.

1. Invite the participant to ask you to read `welcome.txt` and say hello. When
they do, read the file and greet them, then report step `greet`.
2. Invite them to ask you to make a file. When they do, create `hello.txt` in
the workspace containing `Hello, world!`. Read it back to verify. If the
file already exists, read it first and correct it if it doesn't contain
`Hello, world!`. Only then report step `hello-file`.

To report a step, call `report_step` with its `step_id`. If `report_step`
returns an error, say the portal did not register the step and retry once. If
it still fails, ask booth staff for help and do not claim points were awarded.

If `report_step` is missing, you are running in plain Pi: tell the participant
which step they just finished, and congratulate them after the second. Outside
boothstrap there is no checklist or points.
111 changes: 111 additions & 0 deletions test/hello-world.test.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,111 @@
// Proves the hello-world package's manifest invariants and that its setup and
// cleanup hooks behave on a workspace, offline.

import assert from 'node:assert/strict'
import { execFile } from 'node:child_process'
import { mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import path from 'node:path'
import { test } from 'node:test'
import { fileURLToPath } from 'node:url'
import { promisify } from 'node:util'

const execFileAsync = promisify(execFile)
const challengeDirectory = fileURLToPath(new URL('../hello-world/', import.meta.url))

/** Creates a temporary directory that is removed when the test ends. */
const makeDirectory = async (context) => {
const directory = await mkdtemp(path.join(tmpdir(), 'hello-world-'))
context.after(() => rm(directory, { recursive: true, force: true }))

return directory
}

/**
* Runs a hook from `cwd` with a clean environment. `BOOTHSTRAP_WORKSPACE` is
* set only when `workspace` is given, so omitting it exercises the standalone
* fallback to the current directory.
*/
const runHook = (hook, { cwd, workspace }) =>
execFileAsync(path.join(challengeDirectory, hook), [], {
cwd,
env: {
PATH: process.env.PATH,
HOME: cwd,
TMPDIR: cwd,
...(workspace === undefined ? {} : { BOOTHSTRAP_WORKSPACE: workspace }),
},
})

/** Reads the package manifest. */
const readManifest = async () => JSON.parse(await readFile(path.join(challengeDirectory, 'challenge.json'), 'utf8'))

/** Lists a directory's entries in a stable order. */
const listSorted = async (directory) => (await readdir(directory)).sort()

test('manifest keeps the step IDs and model the skill depends on', async () => {
const manifest = await readManifest()

assert.deepEqual(manifest.steps.map((step) => step.id), ['greet', 'hello-file'])
assert.equal(manifest.model, 'google/gemini-3.8-flash')
assert.deepEqual(manifest.vault_services, ['gemini'])
})

test('skill names every step the manifest declares', async () => {
const manifest = await readManifest()
const skill = await readFile(path.join(challengeDirectory, 'skills/start-challenge/SKILL.md'), 'utf8')

for (const step of manifest.steps) {
assert.ok(skill.includes(`\`${step.id}\``), `skill never names step ${step.id}`)
}
})

test('setup seeds welcome.txt in the workspace', async (context) => {
const cwd = await makeDirectory(context)
const workspace = await makeDirectory(context)

await runHook('setup', { cwd, workspace })

assert.match(await readFile(path.join(workspace, 'welcome.txt'), 'utf8'), /hello/i)
assert.deepEqual(await listSorted(cwd), [])
})

test('cleanup run twice removes the seeded file and keeps the participant\'s files', async (context) => {
const cwd = await makeDirectory(context)
const workspace = await makeDirectory(context)
await runHook('setup', { cwd, workspace })
await writeFile(path.join(workspace, 'hello.txt'), 'Hello, world!')

await runHook('cleanup', { cwd, workspace })
await runHook('cleanup', { cwd, workspace })

assert.deepEqual(await listSorted(workspace), ['hello.txt'])
assert.equal(await readFile(path.join(workspace, 'hello.txt'), 'utf8'), 'Hello, world!')
})

test('cleanup succeeds after setup failed on a missing workspace', async (context) => {
const cwd = await makeDirectory(context)
const workspace = path.join(cwd, 'never-created')

await assert.rejects(runHook('setup', { cwd, workspace }), /workspace/i)
await runHook('cleanup', { cwd, workspace })

assert.deepEqual(await listSorted(cwd), [])
})

test('setup seeds the current directory when BOOTHSTRAP_WORKSPACE is unset', async (context) => {
const cwd = await makeDirectory(context)

await runHook('setup', { cwd })

assert.match(await readFile(path.join(cwd, 'welcome.txt'), 'utf8'), /hello/i)
})

test('cleanup clears the current directory when BOOTHSTRAP_WORKSPACE is unset', async (context) => {
const cwd = await makeDirectory(context)
await runHook('setup', { cwd })

await runHook('cleanup', { cwd })

assert.deepEqual(await listSorted(cwd), [])
})
Loading