From 26a87bec3234437ad2a233f66e76df95721936c1 Mon Sep 17 00:00:00 2001 From: Justin Parker Date: Tue, 17 Nov 2026 18:08:02 -0800 Subject: [PATCH] Release 3.1.1: relicense under Apache 2.0 and rewrite the README and site around the six steps AI Assisted --- .github/ISSUE_TEMPLATE/bug.yml | 31 +- .github/ISSUE_TEMPLATE/config.yml | 10 + .readme/README.md | 23 + .readme/activities.md | 1021 ++++++++++ .readme/launcher.md | 43 + .readme/metrics.md | 2 +- .readme/steps.md | 107 ++ .readme/walkthrough.md | 6 +- .readme/web-console-internals.md | 293 +++ .readme/web-console.md | 1661 +---------------- AGENTS.md | 6 +- CHANGELOG.md | 32 +- NOTICE | 1 + QUICK-REFERENCE.md | 22 +- README.md | 306 +-- SECURITY.md | 13 + docs/fonts/archivo-latin.woff2 | Bin 0 -> 92788 bytes docs/fonts/martian-mono-latin.woff2 | Bin 0 -> 38500 bytes docs/index.html | 176 +- docs/robots.txt | 4 + docs/screenshots/activities-dark.webp | Bin 0 -> 123946 bytes docs/screenshots/activities-light.webp | Bin 0 -> 131330 bytes docs/screenshots/app-launch-dark.webp | Bin 0 -> 30962 bytes docs/screenshots/app-terminal-dark.webp | Bin 0 -> 37000 bytes docs/screenshots/ask-dark.webp | Bin 101034 -> 109950 bytes docs/screenshots/ask-light.webp | Bin 109640 -> 118126 bytes docs/screenshots/build-dark-1280.webp | Bin 0 -> 48706 bytes docs/screenshots/build-dark.webp | Bin 121726 -> 124056 bytes docs/screenshots/build-light.webp | Bin 125178 -> 127152 bytes docs/screenshots/dashboard-dark.webp | Bin 92168 -> 91190 bytes docs/screenshots/dashboard-light.webp | Bin 97700 -> 97218 bytes .../screenshots/dashboard-plan-dark-1280.webp | Bin 0 -> 34544 bytes docs/screenshots/dashboard-plan-dark.webp | Bin 91344 -> 89172 bytes docs/screenshots/dashboard-plan-light.webp | Bin 99514 -> 93424 bytes .../screenshots/dashboard-utilities-dark.webp | Bin 123644 -> 162196 bytes .../dashboard-utilities-light.webp | Bin 134746 -> 174554 bytes docs/screenshots/deps-dark.webp | Bin 0 -> 106676 bytes docs/screenshots/deps-light.webp | Bin 0 -> 112874 bytes docs/screenshots/doc-dark.webp | Bin 119664 -> 125914 bytes docs/screenshots/doc-light.webp | Bin 124694 -> 131580 bytes docs/screenshots/finish-dark.webp | Bin 98894 -> 101340 bytes docs/screenshots/finish-light.webp | Bin 103888 -> 106030 bytes docs/screenshots/git-dark.webp | Bin 74708 -> 69644 bytes docs/screenshots/git-light.webp | Bin 80168 -> 73594 bytes docs/screenshots/learning-dark.webp | Bin 0 -> 149110 bytes docs/screenshots/learning-light.webp | Bin 0 -> 160162 bytes docs/screenshots/lessons-dark.webp | Bin 0 -> 112176 bytes docs/screenshots/lessons-light.webp | Bin 0 -> 121000 bytes docs/screenshots/loop-banner-dark.webp | Bin 0 -> 28968 bytes docs/screenshots/loop-setup-dark.webp | Bin 0 -> 32990 bytes docs/screenshots/loop-stop-dark.webp | Bin 0 -> 33162 bytes docs/screenshots/notebook-dark.webp | Bin 0 -> 67404 bytes docs/screenshots/notebook-light.webp | Bin 0 -> 75924 bytes docs/screenshots/notepad-dark.webp | Bin 63890 -> 0 bytes docs/screenshots/notepad-light.webp | Bin 69026 -> 0 bytes docs/screenshots/prototypes-dark.webp | Bin 0 -> 63328 bytes docs/screenshots/prototypes-light.webp | Bin 0 -> 68600 bytes docs/screenshots/question-dark-1280.webp | Bin 0 -> 47476 bytes docs/screenshots/question-dark.webp | Bin 111616 -> 113480 bytes docs/screenshots/question-light.webp | Bin 122176 -> 122302 bytes docs/screenshots/signoff-changes-dark.webp | Bin 0 -> 127362 bytes docs/screenshots/signoff-changes-light.webp | Bin 0 -> 134698 bytes docs/screenshots/signoff-dark-1280.webp | Bin 0 -> 40596 bytes docs/screenshots/signoff-dark.webp | Bin 99512 -> 105338 bytes docs/screenshots/signoff-light.webp | Bin 107620 -> 112262 bytes docs/sitemap.xml | 6 + docs/social-card.png | Bin 0 -> 253004 bytes package.json | 6 +- plan2code-metrics/package.json | 2 +- scripts/make-site-images.mjs | 43 + scripts/make-social-card.mjs | 27 + scripts/social-card.html | 29 + version.json | 8 +- 73 files changed, 1998 insertions(+), 1880 deletions(-) create mode 100644 .readme/README.md create mode 100644 .readme/activities.md create mode 100644 .readme/launcher.md create mode 100644 .readme/steps.md create mode 100644 .readme/web-console-internals.md create mode 100644 NOTICE create mode 100644 SECURITY.md create mode 100644 docs/fonts/archivo-latin.woff2 create mode 100644 docs/fonts/martian-mono-latin.woff2 create mode 100644 docs/robots.txt create mode 100644 docs/screenshots/activities-dark.webp create mode 100644 docs/screenshots/activities-light.webp create mode 100644 docs/screenshots/app-launch-dark.webp create mode 100644 docs/screenshots/app-terminal-dark.webp create mode 100644 docs/screenshots/build-dark-1280.webp create mode 100644 docs/screenshots/dashboard-plan-dark-1280.webp create mode 100644 docs/screenshots/deps-dark.webp create mode 100644 docs/screenshots/deps-light.webp create mode 100644 docs/screenshots/learning-dark.webp create mode 100644 docs/screenshots/learning-light.webp create mode 100644 docs/screenshots/lessons-dark.webp create mode 100644 docs/screenshots/lessons-light.webp create mode 100644 docs/screenshots/loop-banner-dark.webp create mode 100644 docs/screenshots/loop-setup-dark.webp create mode 100644 docs/screenshots/loop-stop-dark.webp create mode 100644 docs/screenshots/notebook-dark.webp create mode 100644 docs/screenshots/notebook-light.webp delete mode 100644 docs/screenshots/notepad-dark.webp delete mode 100644 docs/screenshots/notepad-light.webp create mode 100644 docs/screenshots/prototypes-dark.webp create mode 100644 docs/screenshots/prototypes-light.webp create mode 100644 docs/screenshots/question-dark-1280.webp create mode 100644 docs/screenshots/signoff-changes-dark.webp create mode 100644 docs/screenshots/signoff-changes-light.webp create mode 100644 docs/screenshots/signoff-dark-1280.webp create mode 100644 docs/sitemap.xml create mode 100644 docs/social-card.png create mode 100644 scripts/make-site-images.mjs create mode 100644 scripts/make-social-card.mjs create mode 100644 scripts/social-card.html diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml index 4886d4e..ef81a01 100644 --- a/.github/ISSUE_TEMPLATE/bug.yml +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -32,20 +32,32 @@ body: label: Which skill or tool? options: - Dashboard (/plan2code) - - Init / Init Update + - Init / Init update - Pathfinder - - Plan / Revise Plan - - Quick Task + - Plan / Revise plan - Document - Implement / Implement + Review - - Review - - Finalize - - Handoff - - Web console (page itself) - Implementation Loop (desktop app) + - Finalize + - Quick task + - Review + - X-ray + - Diagnose + - PR Prep + - Test + - Dead Code + - Update dependencies + - UI Prototype + - Git + - Changelog + - Handoff + - Learning + - Activities (the games) + - Web console (page itself) + - The plan2code launcher (command line) + - Installer - Metrics - Status line - - Installer - Other validations: required: true @@ -55,6 +67,7 @@ body: label: Where were you working? options: - Web console + - Desktop app - Terminal - Not sure validations: @@ -64,7 +77,7 @@ body: attributes: label: Plan2Code version description: Found in version.json, the installer banner, or at the bottom of the web console's Help dialog. - placeholder: "2.4.0" + placeholder: "3.1.0" - type: input id: environment attributes: diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 3ba13e0..1aac6f3 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1 +1,11 @@ blank_issues_enabled: false +contact_links: + - name: Read the docs + url: https://plan2code.jparkerweb.com + about: The guides, the quick reference and the walkthrough. + - name: Desktop app guide + url: https://github.com/jparkerweb/plan2code/blob/main/docs/desktop-app.md + about: Install, start, update and the not-code-signed prompts of the desktop app. + - name: Report a security problem + url: https://github.com/jparkerweb/plan2code/security/advisories/new + about: Report a vulnerability privately, not as a public issue. diff --git a/.readme/README.md b/.readme/README.md new file mode 100644 index 0000000..bfda655 --- /dev/null +++ b/.readme/README.md @@ -0,0 +1,23 @@ +# Plan2Code guides + +The long-form guides that sit beside the [README](../README.md). The README is the short version: what Plan2Code is and how to install it. + +## Using + +- [walkthrough.md](walkthrough.md): one feature from a sentence to archived specs, session by session. +- [web-console.md](web-console.md): the web console guide, from the dashboard to the last sign-off. +- [steps.md](steps.md): what each of the six steps asks, writes and hands on. +- [launcher.md](launcher.md): the `plan2code` command, its flags, and using an agent other than Claude Code, Devin or Codex. +- [activities.md](activities.md): the small games behind the die in the console's top bar. +- [status-line.md](status-line.md): the optional three-line Claude Code status bar. + +Also: [QUICK-REFERENCE.md](../QUICK-REFERENCE.md) (the one-page card) and [docs/desktop-app.md](../docs/desktop-app.md) (the desktop app and the Implementation Loop). + +## Maintaining + +- [web-console-internals.md](web-console-internals.md): how the console works, its security model, every route, driving it by hand and refreshing the screenshots. +- [web-console-design.md](web-console-design.md): why the console is shaped the way it is. +- [metrics.md](metrics.md): `plan2code-metrics`, measuring and improving the prompts themselves. +- [test-bot.md](test-bot.md): `plan2code-bot`, the harness that runs the whole workflow unattended. + +For the code layout, see [AGENTS.md](../AGENTS.md). diff --git a/.readme/activities.md b/.readme/activities.md new file mode 100644 index 0000000..07edf0b --- /dev/null +++ b/.readme/activities.md @@ -0,0 +1,1021 @@ +# Activities + +The small games behind the die in the web console's top bar. This is the full guide to each game and to the rules they share; the console guide has the short version. Back to [the web console guide](web-console.md#activities). + + +The **die** in the top bar, right of the megaphone, opens **Activities**: small +games to play while you wait, say through a long build. Thirteen ship today, +**Snake**, **Mini golf**, **Light Trails**, **Bug Hunt**, **Sunset Drive**, **Stack Deploy**, **Bumper Ring**, **Rapids Run**, **Hot Potato**, **Crossing Rush**, **Bounce Road**, **Ghoul Rush** and **Flock Dash**. The window opens on a +**picker**: a row per game, in two columns on a wide window, with a small cover +scene, a line about it, its best score, and a **Last played** tag on the one you +played last, which also has the focus. The **Order** bar above sorts the games +you have played by **Recently played** or **A to Z** (your choice is kept), and +games you have never picked sit at the end under **Not played yet**. Click a row +(or walk the rows with the arrows and press space or Enter) to open its game, +and **All games** at the bottom left goes back to the picker. One game plays at +a time: going back keeps a round paused on its row (**Paused at 14**), +reopening the window goes straight back into a +paused round, and picking a different game ends it. While a game is on screen, +the header shows its best, such as **Activities · Snake best: 12**, or +**Snake: no best yet**. + +Every game has its own soundscape, all made in the browser with no audio +files: engines that rev and shift gears with your speed, outboard motors, +rivers, wind, light-cycle drones and the moans of nearby monsters run for as long as +the moment lasts, and crashes, splashes, explosions, pickups, combos, bosses, +new bests and game over each get a sound of their own. A game can play +chiptune music too, made the same way, which builds as play heats up (Sunset +Drive has a song for each road, Snake a different one at every level, dealt from ten at +the start of a round so none repeats, and Ghoul Rush a track for each room, played at +one steady level and fuller in a boss fight, and Bounce Road a radio of twenty fast +arcade tunes in a shuffled order, with an extra voice for a boss and another in a +Fever), and Light Trails and Flock Dash play five +recorded songs each as background music, each in full, one after another in an +order shuffled for every run: **Play activity music** in **User +Preferences → Sounds & activities** is on by default (turn it off there). **Play activity sounds** there turns the games' +sounds (the 3, 2, 1 and the new-best burst included) and their music on or +off and leaves the page's own cues alone; the **Play sounds** switch above it +silences all of it, and a paused or closed game goes quiet at once. A game +with music has its own **Music** slider beside **Full screen**, which sets that +game's music volume and is remembered per game (Snake, Light Trails, Sunset Drive, Bounce Road and Flock Dash start at 70, +Ghoul Rush at 65). + +- **Snake** gives you three lives: a crash costs one and puts the snake back mid-board with its length and score, flickering through 2.5 seconds of free passage. A life is earned back at 100, 250, 450 and 700 points, then every 300, up to nine (the endless-lives code works here too). Levels 4, 6 and 8 open with a boss that wanders the board while the food becomes its orbs: the Grumpy Golem stomps rocks down, the Comet Queen throws comets and the Thunder Toad leaps where a ring warned. Each orb eaten costs the boss a hit point, touching it is a crash, and beating it earns a life. +- **Snake** speeds up as it grows: 120 ms a step at its starting three cells, + 4 ms quicker for each cell beyond, never under 60 ms, and 3% quicker again + for each level. Every 5 foods is a new level, which opens with Slow-mo on + for its full 7 seconds (Slow-mo eases back to the usual pace over its last + 2.5 seconds, so its end is never a jolt), and the first few each bring + something new: **Rocks** at level 2 (a cell flashes before it turns to + stone, and never right ahead of the head), **Mystery boxes** at 3, + **Portals** at 4, **Comets** at 5 (into the head is a crash, through the + body cuts the tail there), **Chaos** at 6, where surprises also happen on + their own, and **Ice** at 7, where a turn slides on for two steps before it + takes (a frosty arrow off the head shows the turn coming; the ice melts at + level 8). Each level serves its own fruit (an apple, then cherries, an + orange, grapes, a banana, a strawberry, watermelon, a peach and, at level 9, + a glinting golden apple) on its own scenery: a plain garden, then a meadow, + a desert, a lagoon, a starry night, a carnival, ice, a volcano and gold, + each a faint tint and a scatter of small marks over the usual board. The + last food of every odd level from 3 on is a **boss fruit**: four cells big + and crowned, it takes three bites (a point a level each, and the head must + leave it between bites), and the last bite scores the food plus 5 points a + level. From level 2 a **runaway fruit** on two little feet sometimes turns + up in place of a power-up: once you are within three cells it hops up to two + cells away, rests two steps between hops and tires after seven, so corner it + or wear it out for 6 points a level before it runs off after 12 seconds. Food eaten within 2.6 seconds of the last builds a + combo (x2 up to x5). Power-ups turn up every few seconds and fade if left: **Shield** + (takes one crash: wraps through a wall, smashes a rock), **Slow-mo**, **Magnet** (food slides toward you), + **Ghost** (walls wrap) and **Scissors** (half the tail, a point per cell + cut). A mystery box holds one of nine surprises: Jackpot, Gold rush, Earthquake, + Meteor shower, Lights out, Disco fever (triple + points), Big snack, Incoming! (a comet) and Treasure. Passing your best + mid-round plays a fanfare. A power-up, surprise or level banner opens on + the half of the board away from the snake's head, and fades almost clear + while the head is under it or heading into it, so it never hides what you + are about to hit. The start and end screens show how many of the 22 + power-ups, surprises, levels and specials you have ever found, and what to look for + next. +- **Mini golf** is six themed courses of eighteen hand-made, thoroughly silly + holes, seen from above. Its card opens a **course dashboard**: a card per + course with a picture of one of its holes, its line, its holes and par, and + your best round on it (each course keeps its own), walked by the arrows like + the picker, with **All courses** to get back. Once a round is over, space + or a click goes back to the dashboard to pick the next course. **Dino Valley** has tar pits, + geysers, raptors, a stomping T-rex and a volcano finale; **Candy Carnival** + has gumdrops, gummy bears, licorice belts, a soda whirlpool and a chocolate + fountain; **Cosmic Glow** is black-light glow golf in space, with black holes + that pull a putt in, repulsor planets, wormholes, UFOs and airlocks; and + **Frosty Peaks** glides on ice past penguins, a yeti, icicle gates and a + frozen waterfall. Two hazards are theirs: ice, where the ball barely slows, + and gravity wells, which pull it in or push it away. Pirate Cove and the + Caves of Doom are eighteen holes each too, and their first holes are these. + **Pirate Cove** floats in a shark sea: Walk the Plank, + Shipwreck Cove, Cannon Alley, Treasure Beach, Kraken's Lagoon, Ghost Ship, + The Ship's Wheel, Skull Island and, at the end, Captain's Plunder, with barrels, + cannonballs, a rolling powder keg, a scuttling crab, a kraken's tentacle and a + skull you putt through. The **Caves of Doom** are dark but for + the ball's own light and whatever glows: Into the Dark, Stalagmite Forest, + Lava Lake, Mine Cart Madness, Crystal Pinball, The Bottomless Pit, Glowworm + Grotto, Crusher Corridor and The Dragon's Hoard, with glowing pools, lava, a + bottomless pit, a bobbing fireball, runaway mine carts, stone crushers that + slam shut in turn, portals and a sleeping dragon. Each hole opens with a quip, + and splashes, bonks and tunnels pop up a word or two. Play is quick and + arcade style: the aim follows the mouse (or hold left or right to turn it, + slowly at first, then faster), and it points back at the cup each time the + ball stops, staying there until the mouse moves a few pixels, so a click + without a move putts along the arrow you see. A click or space starts the power meter beside the ball; a second + sets the power. The needle crawls near the bottom, so soft putts are easy, + and races near the top: the gold **MAX** band just under full putts 1.15 + times as hard, and the red band past it is an overswing that shanks the ball + off line at reduced power. A ring round the waiting ball is the shot clock: + after 6 seconds the meter starts by itself, and a meter left for three trips + dribbles the ball a few inches. Hold space or the mouse button while the ball + rolls to play it three times as fast. Par is set per hole (59 for the + round), the ball is picked up after 8 strokes, and the round shows its +/- + par. A scorecard (front nine and back nine) shows between holes; space, a + click or 1.5 seconds moves on. +- **Power-ups.** A glowing pad the ball rolls over is held for your next putt + only (the pill at the bottom right says which): a **Lucky Doubloon** makes the + putt free (a hole still scores at least 1), a **Cannonball** fires it 1.6 + times as hard, a **Ghost Ball** floats over water, sand, bumpers and movers + (but sinks if it stops on water), a **Parrot Magnet** bends it toward the cup, + a **Rubber Duck** keeps its full speed off walls, a **Treasure Map** makes the + cup huge, and a **Spyglass** draws where the putt will roll while the meter + runs, following the needle. One + is held at a time, a new pad replaces it, and a held one carries over to the + next hole. +- **Light Trails** is a race to be the last rider moving. You, with Planny's + star eye, and one to three rivals each leave a glowing wall behind; a wall, a + trail (yours too), a crystal or another rider's head is out, and a rival's + trail goes once it has faded. You get a split second of grace: about to + ride into something, you hold in place for 190 ms first, and a turn pressed + then rides out of it (the rivals get none). Arrows steer and space spends a **boost** + charge for 1.4 seconds of speed (two charges a heat, up to three). A round + is a run of heats through nine arenas, each with its own scenery: Neon Grid, + Sunset Strip, Crystal Field, Warp Zone, Storm Front, Carnival, Glacier, + Volcano and the Golden Arena. Winning a heat moves you to the next arena; a + crash costs one of your five lives and runs the heat again, and you and the + last rival out at once is a draw that costs nothing. Every 750 points gives + a life back (up to nine). Each arena brings something: a second rival and + **power-up pads** at 2 (**Boost**, a charge; **Phase**, ride through trails + for 3 seconds; **Eraser**, wipes the trails around you; **Slow-mo**, the + rivals crawl; coins; a beating **Heart**, a life; and a **Shield**, held + from heat to heat until it takes a crash for you, wiping the trails around + you and riding on), **crystals** at 3 with a **Laser** (for 6 seconds it + fires at any rival head in your line up to 16 cells ahead, cutting through + trails but not crystals, three shots, each a rival out with the cut bonus) + and **Score x2** (8 seconds of double points), a third rival and a pair of + **portals** at 4 with a **Wide Trail** (4 seconds of a wall three cells + across; you can turn onto the side cells you have just laid, so a corner + never crashes you) and **Coin Rain** (seven coins over the board), **closing walls** + at 5 (from 10 seconds in, the outer ring turns to stone every 3.5 seconds, + flashing red first) with a **Hyperjump** (straight out to the most open + space on the board), and at 6 a second pair of portals and a rainbow + **Mystery** pad that turns into any of the others. The first pad of each + kind in a run says it is new. The rivals ride sharper each arena, and grab + a pad if they get there first. Points come for riding (a point a level + every 6 cells), for each rival out while you still ride (10 a level, 5 more + when your trail or laser got it), coins and each heat won (25 a level). The + start and end screens show the furthest arena you have reached and the + next one waiting. +- **Bug Hunt** is an arcade shooter. Planny's ship slides along the bottom + (left and right move it, up and down a little too) and fires while space is + held. Each wave of bugs swoops in from the sides into a formation that sways + across the top, and every couple of seconds one or more break off and dive + at you; a bug that misses flies back in from the top. A bomb or a bug that + reaches the ship costs one of three lives, and the ship comes back after a + second, blinking and safe for a moment more. The first waves each bring a new + bug: the everyday **Bug** (wave 1), the **Beetle** (2, two shots, and it + splits into two bugs that dive on their own), the **Race condition** (3, + zigzags as it dives), the **Exception** (4, throws at you), the **Null + pointer** (6, shots pass through it while it fades) and the **Firewall** (7, + five shots, never dives). Every fifth wave is a boss with a health bar: the + **Memory Leak** (grows while you wait and sprays drops), the **Spaghetti + Monster** (shrugs off every shot until its four meatball tentacles are shot + off) and the **Heisenbug** (blurs, then turns up somewhere else, and cannot + be hit while it blurs), then round again with more health. Squashed bugs + drop coins and, now and then, a power-up: **Spread shot**, **Rapid fire**, + **Shield** (takes a hit, up to two), **Slow-mo** (the bugs and their bombs at + half speed), **Magnet** (coins come to you), **Refactor** (clears every bomb + and squashes the everyday bugs on screen) and, from wave 4, a **1UP**. Kills + within 1.2 seconds of each other build a combo up to x5. A wave cleared + scores 50 points a wave, and 100 more a wave without a hit; a boss is 500 + points each time round. The board is Snake's checkerboard scrolling past, + with bits of code drifting by, and new scenery every five waves: the + Codebase, Legacy Code, Production and the Cloud. The start and end screens + show how many of the 16 bugs, bosses and power-ups you have found. +- **Sunset Drive** is a road racer against the clock, seen from behind + Planny's convertible on a road drawn a segment at a time, with bends, + hills and scenery scrolling past. Hold up to drive (five seconds to a top + speed of 150 mph), down to brake, left and right to steer; bends push the + car to their outside, and off the road it slows to a quarter of top speed. + Space burns a **nitro** can for 2.5 seconds of a higher top speed (two to + start, up to three). A round starts with 40 seconds on the clock, shown big + in the top middle (in the last ten seconds it blinks red and swells on + every tick), and each + stage ends at a **checkpoint** that adds time (31.5 seconds + at the first, a second and a half less each stage, never under 18) and + 1,000 points a stage. Just before it the road **splits** around a median: + the side you keep to as it begins picks the next road (the board above the + road names both, the gentler on the left, and a postcard of each road + shows in the top corner on its side as the fork is called), and the + median is a wall that holds you to your side. Six roads, each with its own + sky, scenery, bends, hills and traffic, and its own points bonus: **Sunset + Coast** (x1, where every round starts), **Canyon Road** and **Maple + Valley** (x1.2), **Snowcap Pass** (x1.4), **Neon City** (x1.5, the + heaviest traffic) and **Starlight Highway** (x1.8). Catching up with a car + drops you below its speed, and hitting a palm, cactus, rock or other prop + on the shoulder all but stops you. Points come for every stretch of road + driven (times the road's bonus, and 10% more a stage), coins (100), a + **close call** passing a car within a lane at speed (50) and each + checkpoint; **clocks** on the road add 5 seconds. Under 10 seconds the + clock beeps each second, and at none the car coasts to a stop and the + round is over. Spinning **?** boxes on the road hold **power-ups**, queued + up to three (a box past that pays 250 points): while one is held, space + fires the oldest instead of a nitro can, and timed ones run side by side, + one fired again while it runs adding its time. **Rocket Hop** (1.6 + seconds) leaps over traffic and the shoulder, **Ghost Car** (5 seconds) + drives through cars and props, **Coin Magnet** (6 seconds) pulls in every + item across the road, **Monster Truck** (5 seconds) flings the cars it + hits into the sky (150 points each) and flattens props, and **Coin Storm** + turns the traffic ahead into coins at once. The start and end screens show + how many of the six roads you have found. +- **Stack Deploy** is a one-button tower stacker. A block slides back and + forth above the tower, and space, up or a click on the board drops it where + it is drawn: the part over the block below stays, the overhang is sliced + off and tumbles away, and the next block is that much narrower. A block + that misses the tower ends the round, and the camera pulls back to show the + whole tower once. A drop within 3% of the block's width of exact (or the + distance it slides in 18 ms, whichever is more, but never more than half + the block's width) is a **Perfect**: it snaps + on with nothing sliced, the drop's thunk climbs a scale with each perfect in + a row, and every third in a row grows the block back by 8% of the base's + width, never past it. Points: 1 a floor, a perfect 2 more times the run (up + to x5), and a perfect on a **gold** block (from floor 15, about one floor in + twelve) 10 more and twice the growth. The slide speeds up 2% a floor from + floor 10, and floors bring twists: from 20 blocks come from either side and + some turn back partway, from 30 **lag spikes** freeze a block for 150 ms + before it jumps on, from 40 **wind** eases a block in and out as it swings, + from 70 blocks rush through the middle, and from 90 everything is faster. + The tower changes style as it climbs (server racks, office floors from 25, + glass towers from 50, rockets from 75) under a sky that goes from day to + dusk, night and space, and a dashed line marks the highest floor you have + ever reached, which the start screen names with the next style to reach. +- **Bumper Ring** is sumo in bumper cars on a round platform over the void, + seen from above. Held arrows push your car that way (two at once push on + the diagonal), momentum carries it, and cars bounce off each other: the one + closing faster rams and wins the exchange, and two cars leaning on each + other are a pushing match the stronger push wins. Space **dashes**, a burst + the way you push that also makes the car heavier for a moment (two charges + a heat, one back every six seconds, up to three). A car whose center goes + past the edge falls (the last few units hold it back a little, so a push + back in can save it), and the last car on the ring wins the heat. Rivals + let go and rev before they dash, which is your moment to step aside; a + rival that misses near the edge may fly off on its own. A round runs + through nine arenas: **Training Mat** (the Bully), **The Ring** (a heavy + Turtle that holds the middle, and power pads), **Bumper Alley** (the Sniper, + who lines you up against the edge, and bumpers), **Ice Rink**, **Turntable** + (the ring turns, and the Scrapper hunts whoever is nearest the edge), + **Swiss Cheese** (holes that flash, then open), **Magnet Rink** (the middle + pulls, then pushes), **Hall of Mirrors** (the Mirror copies your moves a + beat later, and the ring turns square and back, its corners flashing before + they go) and the **Grand Final**; past it, Final 2, Final 3 and on, each a + little sharper. Each arena keeps what the earlier ones brought. A win moves + you on; a fall costs one of three lives and runs the heat again, and you + and the last rival off together is a draw. After 12 seconds the ring + shrinks 3 units at a time (the band flashes red first) down to a floor, and + a heat still going after that goes to **sudden death** until two cars no + longer fit. Pads (from arena 2): **Heavy**, **Spring** (the next car you hit + goes flying), **Charge** (a dash), **Shield** (bounce back off the edge + once), **Grow**, **Ghost** (pass through cars) and **Slick** (oil behind + you); rivals can take them too. Points, each times the arena: 10 for a + knockout (the last car to touch the one that fell within two seconds gets + it, and your hit carried through another car counts as yours, as does a + rival you rammed into another), with knockouts within 3.5 seconds of each + other building a combo of up to x5 and + two within a second both counting twice; 25 for a heat won, 15 more if you + never teetered at the edge; a point a second alive; and 5 for a rival that + falls chasing you untouched. The start screen names the furthest arena you + have reached, and the end screen says when you went further. +- **Rapids Run** is a fast vertical scroller on a winding river: Planny + pilots a jet-skimmer up a river that scrolls down the board, its banks + narrowing and splitting around islands. The arrows steer, held up speeds up + (twice the points for distance, and less time to react), held down slows + and held space fires. The battery drains all the while, a little faster at + full speed: run over a green charge buoy to top it up, or shoot it for 10 + points if you can spare the charge. A bank, an island, a foe, a bolt or a + flat battery costs one of three lives, and you start the stretch again + from the last dam with a full battery (once a mini-boss's basin is reached, + from the basin's mouth instead, and a dam already blasted stays open). Each stretch, about 20 to 35 + seconds of river, ends at a dam across it: shoot it open to pass (it takes + more shots each stretch, so slow down for it). Eight stretches, **Willow + Run**, **Reed Bend**, **Stone Gate**, **Mill Basin**, **Fog Narrows**, + **Heron Forks**, **Copper Gorge** and **Old Lock**, then Night Water, + Night Water 2 and on, quicker. Patrol skiffs drift from bank to bank and bob mines sit + still from the start; gull drones swoop across, over land and all, from + Reed Bend, bank sentries shoot back from Stone Gate, whirlpools tug you + toward their eye from Fog Narrows and darters swerve into your lane from + Heron Forks. Every fourth dam a mini-boss holds the basin before it, the + river stopped and your battery held while you fight: **the Dredger** (a + fan of bolts), **Ironclad** (rings of bolts, then one at you) and **Old + Leviathan** (a stream that sweeps). Crates hold **Spread shot**, a + **Shield** (one crash of any kind but a flat battery), a **Magnet** (charge + buoys come to you) and a **Surge** (a full battery). Points: 1 for every 5 + units of river, 2 at full speed; 5 for every quarter second you skim a + bank at speed (10 at full speed); 20 to 60 for each foe, times your combo + (sinks within 1.6 seconds of each other, up to x5); 100 times the dam's + number for each dam blasted (once each), and 50 times it more for a + stretch with no life lost; and 400 for each of the first three + mini-bosses, 800 each the next time around and so on, each of which also + gives a life back. The + score shows big at the end, and the start and end screens show the + furthest dam you have blasted. +- **Hot Potato** is arena tag with a fizzing bomb: a merge conflict, its + `<<<<<<<` markers showing. Held arrows run (light momentum, quick to start + and stop), and whoever holds the bomb runs 1.12 times as fast and passes it + on by touching a runner who holds none. The one just handed it cannot pass + it for 0.6 seconds (it flashes white), and while three or more are left + nobody can hand it straight back to the one who just passed it for 3 + seconds (a white ring at their feet shows who is safe). A pass never + leaves its new holder less than 1.4 seconds of fuse (the 0.6 it cannot + pass in, and 0.8 to reach someone): a fuse handed over lower is topped up + to that, on a rival's pass too, once a fuse for each runner. Space dashes: a lunge while you hold it, a dodge while you do not + (two charges, one back every 4 seconds). The fuse starts at 12 seconds, + ticking quicker as it burns, and each fuse after it in a match is 1.5 + seconds shorter, down to 5; whoever holds the bomb at zero is blown out, + and after a moment the bomb lights again on a survivor picked at random. A + match's first fuse never starts on you. The last one standing wins the match + and moves on a venue; blown up, you lose one of three lives and the match + runs again. Nine venues: **Break Room** (the Sprinter, fast but turning + wide, the Hider, who lurks behind cover and is slow in the open, and the + Trickster, who feints before it dashes), **Open Plan** (pickups), + **Server Room** (long rows of racks, and the Pal, who sticks by you), + **Rooftop** (no wall at the bottom: off it is out, and a holder that goes + over takes the bomb with it), **Ice Machine** (slippery patches, and the + Clingy, who hangs just behind the holder), **Conveyor Hall** (belts), + **Blackout** (you see only round yourself, the bombs and the pickups), + **Two Bombs** (two fuses at once, never more than one bomb for every two + runners left) and the **Finale** (shorter fuses, 10 seconds down to 4, ice, + belts and two bombs); past it, Finale 2, Finale 3 and on, each a little + sharper. Rivals get sharper and quicker as you go, crouch before a lunge + (your moment to dodge), and may dodge yours. Pickups (from venue 2, one at + a time): **Freeze** (every fuse stops for 2 seconds), **Sneakers** (1.3 + times as fast for 3 seconds), **Extra Fuse** (2 seconds more on every fuse) + and **Swap** (trade places with a random runner; a holder keeps the bomb). + Points: 10 times the venue for every fuse that ends on someone else (blown + up, or off the roof with it), 2 for each pass you make, 15 more for a hot + pass (under a second left) times your streak of hot passes in a row (up to + x5; a pass that is not hot ends it, and so does a life lost), and 50 times + the venue for a match won. The start and end screens show the furthest + venue you have reached. +- **Crossing Rush** is a lane-crossing race: Planny and two rival hoppers + hop up a strip of lanes eleven cells wide and 30 to 40 rows tall (the view + follows you, and a race bar beside it shows everyone's height), a cell a + hop (an arrow a hop, 0.12 seconds, with one more press queued). Roads of + cars, vans and trucks; rivers of logs and turtles, which you stand on and + ride (the water, or riding off the edge, is a send-back); train tracks + whose lane flashes red with a bell for 1.2 seconds before a train fills it; + and grass rows with bushes and rocks you cannot hop into. A car, a train or + the water sends you back to the last grass row in a spin, never out, where + you stand dazed for 2 seconds (stars round your head) before you may hop + again; rivals sent back are dazed the same. First to the top wins the heat and + moves on a zone; second or third costs one of three lives and runs the + same heat again (same lanes), except that in zones 1 and 2 second place + still gets through. Nine zones, each bringing something new: **Side + Street** (roads, the Hopper, who waits for a clear gap, and the Daredevil, + who takes the tight ones), **Riverside** (logs), **Rail Yard** (trains), + **Turtle Bay** (turtles that dive now and then; the divers wear a red + mark), **Highway** (trucks, lanes that speed up and slow down, and the + Bruiser, quick and pushy through tight gaps), **Night Market** (a dusk, + every lane still in view, brightened by headlights, lanterns and a glow + round each hopper), + **Rapids** (rivers that turn round, with arrows that blink first, and the + Tagalong, who follows a row behind you, then races you to the top), **Ice + Road** (icy lanes that slide you a cell further) and **Rush Hour** + (everything, tighter gaps); past it, Rush Hour 2, 3 and on, quicker each + time. Rivals get sharper as you go: they look further ahead and wait less + after each hop. Pickups (four to six a heat, on the grass): a **Coin** scores + 10 points at once, and a **Spring**, **Shield** or **Horn** goes on your + stack, shown in the pills as the next one space uses and how many wait + behind it. Space uses the oldest: **Spring** leaps two cells the way you + face, over whatever is in between (it stays on the stack when that cell is + shut), **Shield** lets cars and trains pass through you for 3 seconds, and + **Horn** stops the nearest road for 1.5 seconds, for everyone. Pressed + mid-hop, it goes off as you land. The stack empties at every new heat, and + a rival uses a pickup the moment it lands on it. Points: 1 for each row + higher than you had got in the heat, 50 times the zone for a heat won, + times your streak of clean wins (a win where you were never sent back adds + one, up to x3; any other win, a second place or a lost heat ends it), plus + 3 for each row the runner-up still had to go, 5 for a close call (a car or a train + through the cell you just left within a tenth of a second) and 10 for a + coin. Planny's star is your highlight color, and a rival whose color sits + too close to it wears a spare one. The start and end screens show the + furthest zone you have reached. +- **Bounce Road** is a fast arcade road seen from above, in the spirit of + the late 80s cabinets: Planny races a springy toy car up a road laid across + a giant's house and yard, with rival toy cars on it that mean to stop him. + Hold up to drive, down to brake (a toy car never quite stops), the arrows + to steer (a little less in the air) and space to jump, once a press; a + jump needs a little speed and goes further the faster you are. Bump a + rival sideways and it slides: one that leaves the road within 1.5 seconds + of your bump is yours. Land on one and it is flattened while you bounce up + again; land on another before your wheels touch the road and the **bounce + chain** climbs, up to x8. Every stunt in quick succession steps the + **combo**, which multiplies the points once more every third stunt in a + row, up to x4, and runs out after 2.6 seconds without one. Stunts also + fill the **Fever** meter along the bottom of the pills: full, it burns for + seven seconds of double points, with any rival you touch flattened. + Water or a hole under your wheels, a crash or anything landing on you (a + ring or a growing shadow shows where) costs one of three lives, and you go + back a little before the spot, with room to get up to speed. A life comes + back for a stage with none lost, for a boss beaten and at every 8,000 + points, up to five. + - **Gadgets and weapons.** Power-ups lie on the road from the second + stage, and each one's name flashes at the top of the field as you take + it. Some work as you take them: **Spring** (a longer next jump), + **Bubble** (one free save), **Star magnet** and, rarely, an **extra + life**. The rest are gadgets, held one at a time (the pill reads + `TAP x2`) until you **double-tap space**: the first press still jumps at + once, so a jump never waits, and a second within about a quarter of a + second sets the gadget off. **Rockets** (three shots: the first rival or + barrier ahead blows up, and a boss takes a hit), **Oil slick** (two + spills behind you: a rival that crosses one spins off the road, and it is + yours), **Ground pound** (two slams: you drop like a stone and the + shockwave flattens what is near and throws the rest), **Zapper** (every + rival near loses its steering, its tricks and its hops for 3.5 seconds), + **Nitro** and **Mega wheels**. With nothing held, a **Supply truck** turns + up now and then: land on its roof for a gadget. + - **Stages and bosses.** A lap is fifteen short stages of 20 to 35 seconds, + and every third is a boss stage, which opens with rockets on the road. + Each run deals the stages afresh: Chalk Lane first, then ten of the + fourteen plain themes, roughly from gentle to hard, and the five bosses + in a new order with the Cat last. Some stages carry a **twist**, named + under the stage: Rush hour, Gold rush, Lights out, Downpour, Supply drop + or Turbo lane. The themes: **Chalk Lane**, **Hose Creek** (broken + bridges, a sprinkler), **Kitchen Floor** (oil, a rolling orange, the + rolling pin), **Bubble Bath** (soap, faucet jets that throw you up), + **Flowerbed Fork** (forks, ramps, falling flowerpots), **Pinball Alley** + (bumpers that kick you away for points, conveyors), **Homework Desk** + (rolling pencils, slamming books), **Sandbox Run** (road that crumbles + behind you), **Toy Room** (a toy train, a mallet), **Freezer Aisle** (no + grip anywhere, snowballs), **Garden Pond** (swaying bridges, + drawbridges), **Rooftop Gutter** (gusts), **The Floor Is Lava** and + **Night Lights** (everything, in the dark, with lasers across the road). + Every theme also lays stunt pieces: a **kicker** (a big ramp that flies + you over a whole chicane, through a long line of stars), a **wall** of + blocks right across the road (jump it), a **trampoline** (three rows of + spring pads, bounce after bounce) and a **turbo lane** (a narrow run of + boost strips). + The bosses, each in its own arena and each beaten by landing on it (a + rocket or a ground pound counts too): the **Big Rig** lobs barrels at + where you are heading and leaks oil; the **Robo-Vac** sweeps the hall, + then charges back down the road at you, which is your moment to jump on + it; the **Whirlybird** bombs from out of reach, then swoops down to the + road; the **Monster truck** hops at you and drops tires; **the Cat** + slams its paw down and sweeps it across the road. A boss stage lasts + until its boss is beaten: the road keeps coming, and the stage line only + turns up once the boss is flattened. Past the fifteenth stage the run laps: + quicker, keener, and every boss with one more hit in it. + - **Rivals.** The Zigzag, Brick, Frog, Sneak, Nudge, Hauler, Bruiser, + Racer and Cop block, brake, hop, litter, shove and chase. The later ones + each have a trick, named as they first come: the **Blaster** shoots back + down the road (a bolt knocks and slows you, never a life; jump it), the + **Slasher** pulls alongside and its blades come out (keep off its + sides), the **Spike** must never be landed on (bump it off or shoot it), + the **Bomber** leaves lit bombs, the **Phantom** fades out of reach, the + **Splitter** bursts into two Minis when flattened (two more for the + chain), and the **Magnet** drags you toward the edge it hugs. + - **Scoring.** Points come from new road, rivals flattened (each kind its + own, times the chain), blown up and bumped off, jumps over holes, trains, + balls, rollers, lasers, stompers and barriers, big air, close shaves, + stars, bumpers and boost strips (times the combo), a boss (2,000 for + beating it), and each stage line (100 times the stage, a bonus for + beating its par time, and with no life lost 250 more). Each stage is + ranked S, A, B or C, and the end screen lines the ranks up. The game has + its own radio: twenty synthesized arcade tunes, played in a random order. Planny's car is your + highlight color, and a rival whose color sits too close to it wears a + spare one. The start and end screens show the furthest stage you have + reached. +- **Ghoul Rush** is a fast, dark run-and-gun through a haunted house: + Planny sprints left to right through a mansion a room at a time, the view + scrolling with him. The house is pitch dark: you see what his glow, his + flashlight's cone, the candles, the moonlight and the muzzle flash light, + plus the eyes of whatever is waiting in the dark, and now and then + lightning lights the whole room for a moment. Hold left or right to run, + press up to jump (let go early for a short hop), down to drop through a + shelf or, on the ground, to duck (a crow, bat, gargoyle or other swooper + passes over your head if you are down before it reaches you), and hold space to fire his flashlight blaster the way he faces, ten + bolts a second; a bolt tilts toward a monster ahead near his height (and + toward a hovering wraith anywhere the tilt reaches). The blaster heats up + as it fires: about three seconds go at the full rate, then each bolt waits + longer, down to one a second (holding fire or hammering space heats it the + same). A **LIGHT** gauge at the right of the HUD shows it: the bar fills + as the blaster heats and empties as it cools, notched where the bolts + start to slow, pale, then amber near the notch, then red and **HOT** past + it. Let + go of fire and, after a fifth of a second, it cools, the hottest blaster + in about two seconds. Rapid fire's bolts add no heat and ignore it. **Tap + space twice** to use a **secondary weapon** you have picked up, shown by + a glowing icon and count beside the LIGHT gauge and by the same icon over + Planny's head; keep holding after the second + tap and the bolts carry on. The first tap still fires a bolt, feathering + the blaster never throws anything, and hammering space spends one at + most. The weapon you picked up last comes out first, you keep the rest + from room to room and through a lost life, and no weapon ever hurts you. + **Dynamite** (a wide blast on a short fuse), the **Iron Stake** (goes + through a whole line) and the **Bottle Rocket** (three at once: one + ahead, one that climbs and curves down onto the nearest monster above or + ahead, one behind, each going off in a blast with a trail of colored + sparks) turn up anywhere. Each stage has one of its own: + the Manor's **Billiard Ball** (rolls along the floor), the East Wing's + **Cast-Iron Skillet** (three pans circle you, then spiral off screen, each one-shotting what it touches and breaking on it), the + Graveyard's **Grave Salt** (burns the floor, even what is still buried), + the Grounds' **Hedge Sickle** (out and back, hitting on both passes), the + Chapel's **Tuning Fork** (a ring that cracks stone and strikes organ + pipes), the Sanatorium's **Flash Powder** (dazes what is near and shows + what hides), the Village's **Silver Bear Trap** (five a use: two behind, one at your feet and two ahead, each + snapping on the first thing to step in it) and the Mine's Dynamite, by the + bundle. A boss can take only so much from them (about a third of its + health at full force, then next to nothing), so they help a lot without + winning the fight, and one at half health drops its stage's weapon if your + bag is empty. Each room's door opens + once you grab its key, often up on a shelf. A run starts in **the Long + Hall**, an easy walk with only zombies, then goes **stage** by stage: + three rooms, a bonus ride, then a boss (a big **BOSS FIGHT** card shows the + boss, its name and a menacing line first, and the fight waits for a key press), and beating it opens the door. Out of the hall + and out of each boss's room you **choose the next stage** from two + (one, once a single stage is left) never played that run, each card + showing the stage with its boss standing in it: left and right pick one + out, space or up goes in. Clear six stages and the run takes you back to + **Marrow Manor** for the finale, a fight against **the house itself**: on its + front lawn, shoot out every lit window, the only part of it that can be hurt, + while it throws its roof, its carpet and its fence at you, and calls down + lightning and sends crows out of its door the moment you climb the oak. Kill it and you + **escape**, a win. Each stage cleared makes the next quicker and tougher. Every other room keeps a **horde** + pouring in from the edges of the view, mostly ahead, so standing still is + never safe. **Zombies** shamble out of doors in the wall and sprint once + you are close, **crawlers** drag themselves up through loose boards, + **bats** swoop in level passes at your chest, **ghosts** drift through + walls and can only be hit (or hurt you) while solid, **skeletons** throw + bones you can shoot down, **hellhounds** crouch growling, then lunge in a + low arc a jump clears, **widows** hang from the ceiling and drop on you as + you pass under, **wraiths** hover ahead, shriek and dive at where you were + (keep moving, or shoot them first), and **bloaters** lob acid that leaves + burning puddles and burst into more acid when they die. Now and then a + zombie comes as a **runner** (fast, down in one bolt) or a **glutton** + (slow, 15 bolts to kill, a stomp only bruises it, and it never leaps or + climbs), and a widow or a hellhound as a **huntsman**, a big spider on the + floor that crouches and springs at you as high as you are. A shot to the head + or a stomp from above doubles a kill, and each kill within 1.2 seconds of + the last steps the chain, which multiplies kills up to x10. The rooms bring + pits, one-way shelves, crumbling boards and falling chandeliers that crush + whatever is below (a monster crushed counts double). Five stages so + far: **the Manor**, the **Foyer**, the **Portrait Gallery**, the **Library**, the **Grand Banister** + (a **bonus round**: you slide down the grand staircase's banister for about a minute, + jumping vases, candlesticks and the breaks in the rail, ducking hanging portrait + frames and chandeliers on a pendulum (brake or lean to time them), shooting ghostly + butlers and cobwebs, and jumping with DOWN held to dive onto the brass under-rail + where the track splits; five hearts of your own, as in the other bonus rounds), + the **Ballroom** + (the **Rotting Gourd**, a giant rotten pumpkin that picks one of three + moves at random, never one three times running: a hop to where you stood, + its shadow showing where, that shakes loose gourdlings; a spit of two + acid globs after a shake; or a quake straight up and down that sends a + shockwave along the floor both ways). Its arena is stacked with balconies + in three tiers: up on one over its head it only spits at you, never hops, + a corner always leaves a pocket its hop cannot land on, and its gourdlings + jump up onto balconies after you and run off their ends to follow you + down), **the East Wing**, the + **Kitchen**, the **Conservatory**, the **Attic** and the **Crypt** (**Old + Rattlebones**, who throws volleys of five bones, slams shockwaves along + the floor you jump and throws his own skull like a boomerang, level at your + chest and back again, so jump it going and coming; headless meanwhile, he + has no weak spot, but a bolt to the flying skull does triple. His skull on + his shoulders takes double. At half his hp he shakes, his eyes flare and he + fights faster: his slams come in a double, he hurls bones up that come down + around you on shadows, and he raises up to two skeletons out of the floor), + and **the Graveyard**, out + under the night sky: the **Lychgate**, **Open Graves**, **Mausoleum Row** + and **Angel's Rest**; between the Row and Angel's Rest is a **bonus round**, + **the Midnight Hearse**: you hijack a runaway hearse and tear down the + cemetery road for about a minute, switching between the road and the grass + verge at the lane gates to get round fallen oaks and hedge walls, jumping + open graves and headstones, ducking branches and the lychgate arch and + shooting grasping hands and crows, with the lamp kept lit by lanterns on the + road (a hit throws a coffin out ahead, and the ghoul that sits up in it is + worth shooting). Its monsters are its own: **grasping hands** that lie + unseen under the dirt, burst up as you pass and creep along under the + ground after you; **mourners** whose wail slows you to half speed for a + moment if you are close; **grave robbers** who dig in and come up behind + you; **rotters**, zombies whose legs keep walking after you if you shoot + them down at the body (a headshot or a stomp finishes them); **carrion + crows** that wait on the headstones and dive at you; and rotters climbing + out of open graves. Its boss is **Mother Mourning**, a giant weeping angel: + while she weeps she is stone (your bolts glance off) and flings headstones, + then she turns and watches, and only then can she be hurt, but anything + but standing still while she watches brings a stone fist down where you + are, its shadow first. She does not stay where she was: each time she turns + back to watch she has blinked a few steps nearer, in a puff of stone dust. + At half her health she spreads her wings: a shorter weep, two headstones at + a time, a shockwave each way as each weep begins, and while she watches a + stone fist also falls near you now and then, moving or not. + A fourth stage, **the Grounds**, is the gardens under the night sky: the + **Hedge Maze**, the **Topiary Garden**, the **Gazebo** and the + **Groundskeeper's Yard**. Its monsters: **topiary beasts**, hedges clipped + into animals that stand frozen while you face them and charge the moment + your back is turned (so you can only shoot one while it is still); + **rootlings**, a crack that runs along under the lawn after you, stops + to warn, then bursts up as a solid root that hurts until it sinks again; + **lantern moths**, which come in flocks of three and flutter at you, + quicker in the dark and straighter still while you hold the Lantern; and + **mulch crawlers**, which wait in a leaf pile and burst out as you come + near. Its power-up is the **Hedge shears** (10 seconds, found only here): + one bolt cuts down a topiary beast or a rootling outright. Its boss is + **the Groundskeeper**. Jump his scythe as its low wave sweeps along the + floor, but when he raises it high (a pale band hangs in the air in front + of him) stay on the ground and let the high sweep pass over you; shoot the + lantern at his belt while it flares open (it takes triple damage, but only + then, and only briefly: after the scythe and again when the mower stalls); + jump or stand clear of the fire he lobs where you stand, which burns the + floor for a few seconds. At half his health he climbs onto a rusted mower: + when he revs, get up high on a shelf before he charges across the + arena (the charges come a little oftener), then shoot the lantern while he + is stalled against the far wall. On the mower he lobs a second fire where + you are heading, and each time the lantern opens a few lantern moths + flutter in toward it. + A fifth stage, **the Chapel**, is indoors again, candlelit stone and + stained glass: the **Nave**, the **Bell Tower**, the **Organ Loft** and + **the Choir**. Its monsters: **gargoyles**, stone on their ledges (your + shots glance off and a stomp does nothing) until you pass under one, when + it shakes loose, dives at your chest and flies back to turn to stone + again; **choir ghosts**, which drift at you and sing now and then, and + while they sing every monster near them moves faster, so kill them first; + **censer monks**, who walk at you, swing their censers and leave clouds of + harmless smoke that hide what is inside; and **bell bats**, asleep in the + bells until the bell tolls. The **bell toll** is the stage's twist: in the + tower and the choir the bell swings in view, then tolls, and for one + second everything freezes, you included (a bolt already flying still + hits), while a flock of bats bursts from every bell in view. Its power-up + is **Holy Water** (10 seconds, found only here): your bolts splash, + hurting every monster close to what they hit, hurting ghosts twice as much + and breaking a stone gargoyle even on its ledge. Its boss is **the + Choirmaster**, at his organ. Silence the four pipes to open him: each pipe + takes a handful of bolts, a sounding pipe spews a ghost now and then, and + while any pipe sounds he cannot be hurt. Once all four are silent, shoot + him, but not for long: after four more columns of notes, fresh pipes drop + in from the roof and you must silence them again. Between those he raises + his baton and a column of notes flies at you along the lines of a staff + with one gap in it: mind the gap in each column and be at its height (the + floor or one of the boards) as it passes. Each column has its own speed, + some far faster than others (a hot edge and a long tail) and some slower (a + cold edge and a short tail). At half his health the hymn quickens: the + notes fly faster and now and then a second column follows close behind. + Between the Organ Loft and the Choir is a + **bonus round**, **Holy Roller**: an endless-runner seen from behind. You + surf a runaway church pew down the nave's aisle toward the altar, in three + lanes, faster and faster for about a minute, with stone pillars, stained + glass and pews rushing past in candlelight. LEFT and RIGHT change lane (a + press at the edge bumps the wall), UP jumps, DOWN slides (in the air it + fast-falls), and holding space shoots straight down your lane. Switch lane + around the pillars, confessionals and crosswise pews; jump the kneelers, + candle stands, flagstone cracks and open crypt hatches; slide under the + swinging censers, hanging banners and fallen beams; shoot the gargoyles + that drop from the arches (two bolts) or shoot a bell rope to ring its bell + and stun the gargoyles ahead. Rows of golden wax souls run along the lanes + (arcs over jumps, lines through slides) and build a combo, and a halo + pulls the souls beside you in for a few seconds. Taking most of the souls + is worth a Lucky Die. It plays for five hearts of its own, so a hit costs a + heart, never a life, and shoves you into a safe lane; lose all five and the + round ends with nothing and the run goes on to the Choir; reach the end and + you earn three to nine Lucky Dice. + A sixth stage, **Blackmoor Sanatorium**, is a derelict asylum of cracked + green tile: **Admissions**, the **Hydrotherapy Baths**, the **Surgical + Theater** and **the Night Ward**. Its monsters: **orderlies**, huge and + slow, which reach for you when you come close (jump clear while they wind + up), grab you and throw you a long way back (the throw costs no life, but + mind where you land); **gurneys**, solid enough to stand on while parked, + which rattle and roll at you when you come along their floor and hurt only + while rolling; **flickers**, gaunt patients you can neither see nor hit + while the lamps are lit, which lunge at you in the dark; and **specimen + bloaters**, which lob jars that shatter into puddles of formaldehyde. The + **flicker** is the stage's twist: in the baths and the theater the lamps + stutter, then go out for a moment, and in that blackout you see little + beyond your own glow. It has two power-ups found only here (10 seconds + each): **Smelling Salts** (you break an orderly's grab at once, and keep a + wide glow through a blackout, in which flickers show and take double + damage) and the **Bone Saw** (your bolts pierce every monster in a line, + and a gurney breaks in one hit). Its boss is **the Night Matron**. Stay out + of her lantern's beam as it sweeps the ward: a moment in it costs a life, + so hide behind a medicine cabinet or climb above it. Between sweeps she + throws fans of syringes, and cracks of light in a wall warn of a long arm + about to reach across the room at your height. At half her health the ward + goes dark, her lantern the only light, her arms come from both walls at + once and her fans of syringes grow. + A seventh stage, **Hollow End Village**, is out under the night sky again + (all but its inn): **Main Street**, **the Crooked Inn**, **the Town + Square** and **the Village Green**. The **moonrise** is the stage's twist: + in each room the moon climbs the sky, and when it is full every villager + in view turns into a fast, leaping wolf-man and the moonhounds grow, so + clear the villagers before the moon is up. Its monsters: the **torch mob**, + villagers who come in threes and lob torches that leave fire on the + ground; **hanged men**, swaying on their ropes until you pass under, when + they drop to head height and haul back up; **shutter ghouls**, which rattle + their shutters as you come near, then lunge out of the window (shoot them + while they are out); and **moonhounds**, which leap at you like + hellhounds. Its power-up is **Wolfsbane** (10 seconds, found only here): + wolf-men and moonhounds shy away from you, and your bolts do them and the + Beast double damage. Its boss is **the Beast of Hollow End**, a werewolf. + It bounds onto the walls at either end of the green and clings there a + moment, the time to shoot it for double damage, then pounces where you + stand (watch the shadow on the grass); up close it swipes, and its howl + calls moonhounds. At half its health the moon comes full: it waits less, + pounces twice in a row, and its howl calls grown hounds. Between the + Square and the Green is a **bonus round**, **Torch Mob**: you steal a hay + wagon and race out of Hollow End down the cobbled road and over the old + stone bridge, about a minute and ten seconds, with the village chasing you. + Jump the barrels, crates, ditches and spooked horses, duck the washing + lines and inn signs (down also brakes the wagon), and shoot or dodge the + pitchforks and torches the villagers hurl from windows and roofs (a torch + that lands sets the hay alight). The **mob** behind you closes in when you + brake, get hit or burn, and falls back on clean stretches and when you + shoot their torches; if it catches the wagon it costs a heart, and the + collapsed bridge must be jumped off its ramp. Keeping the mob far behind + is worth a Lucky Die. It plays for five hearts of its own and pays three + to nine Lucky Dice. + An eighth stage, **the Deep Seam Mine**, goes underground, where every room + is always dark: **the Mine Shaft** (ride the cage lifts up and down), + **the Flooded Tunnels** (knee-deep water slows you and your steps splash), + **the Collapse**, **the Runaway Cart** and **the Mother Seam**. **Rockfall** is the stage's + twist: dust trickling from the ceiling warns of a rock about to drop, which + crushes whatever is under it, you included. Its monsters: **Knocker imps**, + small and quick, whose touch steals your light (your glow shrinks to a + sliver for a few seconds, but no life is lost; shoot the imp to get it + back); **canary ghosts**, harmless to touch, but their scream brings three + rocks down around you, so shoot them first; **dead miners**, who burst out + of the walls with their helmet lamps still lit and swing a pickaxe up + close; and **blind crawlers**, which hunt by sound: stand still without + firing for a moment and they lose you. It has two power-ups found only + here: the **Hard Hat** (worn on your head until it is used, like the + Garlic shield: one rock bounces off it, or an imp knocks it off instead of + stealing your light) and bundles of **Dynamite** (three sticks here, + thrown with a double tap like any secondary weapon). Its boss is **the + Tommyknocker**, a miner-giant with a sledgehammer. He knocks on the rock + to bring the ceiling down, sweeps his hammer low along the floor (jump + it), and puts out the lights: in the dark an imp carries his lantern as a + decoy, so follow the knocking instead, and when he bursts out of the floor + he is dazed for a moment and takes double damage. At half his health the + dark lasts longer, his knocks come quicker and imps join in. + **The Runaway Cart** is a ride, not a walk: Planny rides a mine cart down a + roller coaster of track over the chasm and the cart does the moving. It + rolls on its own, quicker down a slope and slower up one; right leans + forward, left brakes, up jumps (left and right steer in the air) and down + ducks. Jump the gaps, the heaps of rubble and the crates (or shoot a crate + twice), duck the low beams, pick the right line where the track splits, and + do not brake for long: a boulder rolls up behind (and once it surges, hold + right to stay ahead of it). It is a **bonus round**: a long, fast ride (about + a minute) played for five hearts of its own, so a hit, a fall off the track + or a flattening costs a bonus heart, never a life, and you come back at the + last checkpoint. Lose all five and the round ends with nothing and the run + goes on to the Seam; get to the buffer stop and the door opens, and you earn + Lucky Dice (three at least, up to nine for hearts left, obstacles passed + untouched, crates broken and monsters shot, and not braking much). + A ninth stage, **the Midnight Carnival**, is a fairground at night: + **the Midway** (booths and counters to hop along), **the Hall of Mirrors** + (indoors), **the Funhouse** (its floors are conveyor belts that carry you + along while you stand on them, slower than you can run) and **the Big Top**. + Its monsters: **grinners**, clowns that honk out a balloon that drifts at + you at chest height (shoot it or it pops by itself, and it leaves a puddle + of acid for a couple of seconds; one on you costs a life, and ducking lets it + float over); **marionettes**, which hang just over your head and drop when + you pass under them (a bolt over its head, on the string, kills one at once, + else it takes four hits); **Mirror You**, which steps out of a mirror, + copies your moves the other way half a second late, and fires a bolt for + every bolt you fire (its bolts and yours cancel when they meet, so fire and + then move); **strongmen**, slow and huge, who lob barbells in an arc (a + stomp hurts one); and **circus hounds**, which crouch while a hoop of fire + flares and then leap, coming down where you stand (a ducked Planny is + passed over). It has two things found only here: **Cotton Candy** (10 + seconds of sticky bolts that slow what they hit) and the **Custard Pie** + (thrown with a double tap in an arc, it splats and leaves everything near + stunned for three seconds; a pied Mirror You copies nothing meanwhile). Its + boss is **the Ringmaster**, on a gantry high over the ring, working a + giant puppet that hangs on three strings and stalks you round the ring: it + leaps to where you stood (watch the shadow, then jump the shockwaves), + charges along the floor to the wall (jump it) and stomps. Shoot the strings, + not the puppet: they follow it and slant as it moves, and from a trapeze + board or in a jump a bolt that crosses a string cuts into it, and + when all three are cut the puppet collapses and the Ringmaster is left + open on the floor for four seconds, the only time he can be hurt. Then he + climbs back and ties the strings again. Now and then he cracks his whip + along the floor at chest height (duck it, or jump it). At half his health the + cages in the wings open and hounds come out, and the strings take more hits. + Between the Funhouse and the Big Top is a second **bonus round**, **the Dark + Ride**: a side-view shooting gallery on rails where Planny sits in a ghost-train + car and twelve rooms of animatronics go wrong (a wax museum, a torture chamber + with the Executioner, a carousel, a hall of mirrors where only the solid ghoul + is real, a tunnel of love with the Black Swan, the Widow's nest, a lift hill, a + burning big top, a fake Exit, the Dark and the Barker), about a minute and a + half. Its title screen waits for a key or a click, and tips you to use the + mouse and to duck by moving your aim below the dashed line. Nothing walks: the **arrows** move an aiming reticle (it speeds up the longer + you hold), **Space** fires (hold to keep firing), and with the **mouse** you + move to aim and click or hold to fire. Pull the reticle down into the car, + below the dashed line, and Planny ducks (he cannot fire while ducked): the + answer to swinging blades, falling chandeliers and the big swings. Shoot + what lights up, chains and webs, and never the green-heart guests or a + mirror's reflections; a shot that just misses still finds a target close + to the reticle (never a guest). You have five hearts of your own and a + hit leaves you safe for a couple of seconds; killing a mini-boss gives one + back. Lose all five and the bonus ends with no dice and the run goes on to the + Big Top, its lives untouched; reach the end alive and you earn five to nine + Lucky Dice by how well you did (the dice pop out in a cascade). + A tenth and last stage, **the Frozen Lake**, is a frozen lake at night under + falling snow: **the Ice Fishing Huts** (open ice with holes in it), **the + Snowbound Lodge** (indoors, a hall the roof fell into), **the Black Ice** + (the longest room, ice nearly everywhere) and **the Widow's Web**. Between + the Black Ice and the Widow is a third **bonus round**, **the Coffin Sled**. + Two rules are its own and work in any room that sets them. **Ice** is + slippery: on it Planny's run eases up and eases off, so he slides a dozen + units past where you let go, a jump keeps the speed you had, and he stops + dead at the ice's edge. **Thin ice** is a tile that shows a crack when you + stand on it, breaks a moment later (the floor is a gap, and if you are on it + a life is lost: "went through the ice") and freezes again after a few + seconds; step off in time and it heals. Its monsters: **under-ice hands**, + which trail you beneath the ice, crack a thin tile under you or burst up and + grab (shoot or stomp one); **snow shades**, which you see only by their + footprints until one winds up or a bolt of yours passes near it, so shoot at + the prints; **frozen ghouls**, zombies that slide on ice and shatter when + they die into three shards (two run along the floor, jump them, and one flies + at head height, duck it); and **ice wraiths**, whose dive freezes you for + most of a second if it passes close (one dives at a time). Two things are + found only here: **Hot Cocoa** (10 seconds of no sliding, no freezing and + thin ice that cracks at half the speed) and the **Road Flare** (thrown with + a double tap in an arc, it lands and burns a patch for four seconds: it burns + what walks in without leaving drops, melts a Frozen Ghoul at once with no + shards, lights up a shade, and never hurts you). Its boss is **the Frost + Widow**, who hangs from the roof, drops to the floor and walks at you + behind a veil of ice that guards her. Kick or shoot the burning barrels at + her to melt the veil (a flare does it too); then, with her low, any shot + hurts and the heart takes triple while her mouth is open. A blizzard now and + then pushes you away from her (a barrel in between breaks the wind), ice + spikes rise from the floor where you stand (the line cracks first; a board + of 18 is over them), her web slows you while you are in it, and at half her + health the barrels are set out again and ice wraiths join in. **The Coffin + Sled** is a ride down a long frozen cemetery hill on a coffin lid, about a + minute and a half: the sled speeds up on the downs and slows on the ups on + its own, so you only jump (cracks in the ice, headstones, snowdrifts, hands), + duck (low branches and tombstone arches) and shoot (icicles, popping ghouls + and hands). It plays for five hearts of its own, so a hit costs a heart, + never a life, and a fall into a crack puts you back on the ice ahead. Lose + all five and the round ends with nothing and the run goes on to the Widow; + reach the snowbank and you earn three to nine Lucky Dice (hearts left, + obstacles passed untouched, things shot and souls and Cocoa taken). + **Gallows Bog** is a stage of three walked rooms (the Sunken Boardwalk, + Cypress Hollow and the Stilt House), a bonus round and the Drowning Pool. + Its own rule is **mud**: on a span of it Planny sinks the longer he stands, + the run sags to a crawl and a jump to a low hop over about two and a half + seconds. Dry floor, the air, a board over the mud or **Stilt Boots** (ten + seconds, found only here) let go of it, and the sink drains away. Its monsters: the **lurker**, + two eyes at the waterline that nothing touches or shoots until you come + within nine units, then it snaps out at you and sinks back; the **leech + swarm**, which drifts at you through the wet and latches for one heart, drops + off and cannot latch again for a moment (a hit breaks it up); the + **will-o'-wisp**, whose light draws every monster within ten units of it + toward you at a fifth more speed until a shot puts it out (it stays dim for + six seconds, glows where it will return and then burns again); and the **bog + body**, which climbs out of the mud harmless and then shambles. The **Harpoon** + is the stage's own weapon (a double tap): it pierces everything in its line + and is the one shot that reaches a lurker's eyes under the water. **The + Drowned Lantern** is the first bonus round that is not a ride: a top-down game + on one screen, an island of mossy hummocks and plank walks round Old Mother + Bog's pool, which you cross with a lantern to light five wisp shrines (stand + on a shrine's stone for two seconds) and then run back to the boat you came + in. The arrows walk; Space flares the lantern, a ring of light that bursts + every wisp in it and scatters the leeches, at the price of some oil and a bang + the Lurker hears from anywhere. The oil burns down and the light shrinks with + it; each shrine lit fills it again. Each hunter plays by one rule, shown over + it the first time it comes near: the **Bog Lurker** hears steps on the planks + (the moss is silent), swims to where it last heard you, then lines up a red + lane through that spot and dashes down it (it strikes where it heard you, so + step off the lane); a **wisp** circles each unlit shrine and rushes a lantern + that comes near it (a flare pops it); the **leeches** follow you at the edge of + your light and never come in, until the oil runs out; the **bog bodies** bubble + beside the planks and grab only someone who stands still next to them. Old + Mother Bog's eyes open a little with every shrine; from the third her hand's + shadow finds you now and then (it follows, stops, reddens and slams: keep + moving), and the fifth raises her out of the pool for the run to the boat, + her slams coming one after another while the Lurker cowers. Like the other + bonus rounds it plays for five hearts of its own (with a 90 second clock) and + ends with three to nine Lucky Dice (hearts left, hunters that never caught + you, wisps popped and close calls, and never letting the flame gutter). The boss is **Old + Mother Bog**, who keeps her distance along the planks: she sends a low wave + of mud to jump, or spits from her cauldron to leave a muck patch that burns + for three seconds (it shows where it will land first). Late in each rest her + cauldron opens, and a shot into it counts triple. At half her health she goes + under, bubbles show where she will come up near you, and she fights on with + shorter waits and a second patch aimed ahead of your feet. + Not every room is dark: each time you enter one it is dark three times in + five and otherwise lit, dim but seen whole (the same for the same run's + seed). The Long Hall, where every run starts, is always lit until you take + its key, and then the lights go out for the rest of the room. In a dark + room only half as many monsters come in from the edge + behind you. Power-ups lie in the rooms and now and then drop from + a kill: **Spread shot** and **Rapid fire** (eight seconds each), a **Garlic + shield** (shrugs off one hit and sees off what touched you; lose a life + within 12 seconds of coming in and you come back already holding one), a + **1UP**, a **Lucky die** (a white die, dropped by a kill as often as a + 1UP and never lying in a room; every run starts with three, up to nine are kept for the whole run, shown + as a **DICE** pill, and a ninth more is points; when you would lose a life, + by any cause but the endless-lives code, the game asks **Use a Lucky Die?** + (arrows choose Yes or No, Space answers, a click works too; a press in the + first moment is ignored so the key you were holding cannot answer). Yes rolls + one die on the field (the rest are kept); No keeps every die and loses the + life as usual. A 4, 5 or 6 brings you back where you fell, or after a pit on the + last ground you stood on, with no life lost and the room as it was: a 5 adds + a heart, a 6 a heart and a Garlic shield, and in an ordinary room every + monster in view blows apart for its points (in a boss's room nothing does). + A 3 or lower loses the life as usual: a 3 brings you back with Rapid fire and + a Garlic shield, a 2 with Bottle Rockets and a Garlic shield, and a 1 only + laughs at you, "Better Luck Next Time"; on your last heart a 2, 3 or 4 instead pays one heart, and you respawn with it as usual; every run starts with 3 dice), a + **Lantern** (15 seconds of the dark pulled far back, found only in a dark + room; in a lit one another power-up lies in its place), **Bat wings** (12 + seconds of one flap in the air per jump, for a second jump; fall down a pit + with them on and they carry you back to the ground you fell from, costing no + life or die, and are used up), a **Church + bell** (4 seconds where every monster but a boss stands still and none + comes, ending at the door) and an **Hourglass** (20 more seconds on the + clock). Every room but a boss's has a **clock** (70 to 80 seconds, its + last ten ticking out loud); at none it costs a life and the room starts + over with a full clock. Two or more zombies, runners, crawlers or + gourdlings bunched under you climb over each other to reach you, arms + raised (land on the arms and they hurt you; only the head between them + takes a stomp), so a shelf over a + crowd is never a safe place to wait. The horde never ends, so its kills + (and those of the dead that come once the bonus is gone) are worth 80% of + the last one in the room, down to a tenth, and drop nothing: farming them + by the door pays next to nothing. A walker at the edge of a pit or a + drop (or a wall up to 8 high, for a zombie, runner or crawler) stops a + moment to think about it (a "?" over it), then leaps (or climbs): across + up to 10 units to floor at its own height, further down to a lower floor, + or straight down off a ledge; a wider pit or floor higher than a step + still stops it. High over each room's key + shelf (but a boss's) float **crystals** (250 points each) and in some + rooms **Silver bolts** (10 seconds of bolts that go on through every + monster they hit, found nowhere else): out of reach of one jump from + anywhere, but a jump and a **Bat wings** flap from the key shelf takes + them, and each such room has Bat wings on the way. + Points: 100 a zombie, 75 a crawler, 50 a bat, 150 a ghost or a hellhound, + 120 a widow, 200 a skeleton or a wraith, 250 a bloater and 40 a gourdling, + all times the chain, 25 a bone or glob of acid shot down, 10 a soul and 50 + a power-up; through a door, 300 times the room number, the time bonus left + (1500, dropping 50 a second; once it runs out, zombies come in from the + edges every second and a half) and 500 more with no life lost; 2000 for + the Gourd and 2500 for Rattlebones (90 hp), a quarter more for each stage + already cleared, with a life back up to nine. A hit or a fall costs one of seven lives and puts you back at the + room's start (in a boss fight, the arena's, the boss's hp kept), safe for + a moment, and on your last life the edges of the view pulse red. The start + and end screens show the most stages you have cleared in a run. When a + room starts again after a loss (a hit, a fall or the clock), a random + power-up shimmers a few steps ahead of Planny on every restart until you + clear the room (never a 1UP, and not in the bonus rides). +- **Flock Dash** is a side-scrolling flight through a sunset sky, with Planny + as the lead bird. Hold up or down to climb and dive within a band in the + left part of the sky, and left or right to ease forward or back. Strays + drift in from the right; fly into one and it joins the flock, which + follows the exact path you flew, each bird a set distance behind the one + before. Balloons, gusts, slipstreams, storm clouds and kites are in the + way: a hit on the leader costs one of three lives, and a hit on the line + snaps it there, scattering the birds behind (fly back through them within + 3 seconds or they are gone). Eight stages, each faster than the last, + each end at a jet stream portal: with enough birds the flock forms a V + and pays a bonus, and the final portal moves. Tailwind, shield and magnet + crates help, pickups in quick succession build a combo of up to x5, and a + stage with no snap and no bird lost pays a flawless bonus. Five recorded + songs play as background music in a shuffled order. The end screen's nudge + to play again names the next hazard or stage you have yet to reach, and the + furthest stage you reached is kept privately. +- **It never hides your turn.** A new question, a sign-off or a finish pauses + the game at once and shows a banner with **Go to it**, which closes the window + on that question, and **Unpause game**. While that banner is up, only + **Unpause game** plays on, so a key or click you were already making cannot + wave the banner away unread. Hiding the page or clicking away from it pauses + the game too, and nothing resumes by itself. Otherwise (after **Go to it**, or + once you close and reopen the window) any game key (arrows, W/A/S/D, space, + P, Enter) or, in Mini golf or Stack Deploy, a click on the board plays on, + and the banner stays down until the next new question or finish. +- **Lives at a glance.** A game with lives shows them as a solid pink pill + with a heart per life, and its banners fade almost clear while you, or + whatever is coming at you, are under them. +- **Endless lives.** In any game with lives, type up, down, up, down, left, + right, left, right, B, A, space on the board: the lives pill turns to + "♥ x∞" and no life is lost until the round starts over (R, or a new round) + or you leave the game for the picker or close the window. +- **Stage select (Ghoul Rush).** Type up, down, up, down, left, right, left, + right, S on Ghoul Rush's board for a practice round that opens on its stage + select: up and down pick a stage, left and right one of its rooms (the last + is the boss's), space goes straight in. A practice run keeps no best score + and no record, and starts with a full stock of that stage's weapon and the + common ones. Endless lives typed before it carry over; typed after, they + last for the run as usual. +- **A countdown first.** Every game counts down 3, 2, 1 before a round starts + and before it plays on after a pause, so nothing moves before you are ready. + P or Esc during the count pauses again. +- **Keys.** Arrows or W/A/S/D steer, space starts and plays (and boosts in + Light Trails, fires while held in Bug Hunt, burns nitro in Sunset Drive, + where held up drives and held down brakes, drops the block in Stack Deploy, dashes in Bumper Ring, where held arrows push, fires while held in Rapids Run, where held up speeds up and held down slows, dashes in Hot Potato, where held arrows run, uses the oldest pickup in Crossing Rush, where an arrow hops once a press, jumps once a press in Bounce Road, where held up drives and held down brakes and a double tap sets off the gadget held, fires while held in Ghoul Rush, where held arrows run, up jumps once a press and down drops through a shelf, and climbs and dives in Flock Dash, where held up and down fly the leader and held left and right ease forward and back), P pauses, R starts the round over (from the 3, 2, 1), F (or **Full screen** under the board) gives the game the whole screen and F or Esc puts it back, and Esc closes the window with the game paused. In full screen the board takes the whole screen, as big as its shape allows, with black bars where the shape leaves room, and a panel (the game's name, the score line, the game's **Music** slider for a game with music, Exit full screen) is laid over it: docked in the side bar when that bar is at least 220 px wide, in the bottom bar on a tall screen when that is at least 110 px tall, and otherwise floating in the top right corner (Sunset Drive's 16:9 board on a 16:9 screen), where it shrinks to the score line in the bottom right corner while a round plays and the pointer is still. The board never gives up room for the panel. The pointer hides after two still seconds. In the desktop app the page asks the app (`activities-full`) to lay the console over its bar and terminal and put the window in full screen, since the app's frame allows the page no full screen of its own. A question, a sign-off or a finish takes a full-screen game back to the window's own size as it pauses it. A page with no mouse or trackpad + (touch only) shows "Activities need a keyboard." in place of the board. +- **Best scores** show beside the score while you play and after each round. + Snake, Light Trails, Bug Hunt, Sunset Drive, Stack Deploy, Bumper Ring, Rapids Run, Hot Potato, Crossing Rush, Bounce Road, Ghoul Rush and Flock Dash keep their highest score. Mini golf keeps its lowest + full round on each course, every course on its own, and a half-played round never counts. **Reset best scores** clears them after a + second click to confirm. + The line under the board is a pair of colored chips, Score and Best, with a + meter between them filling toward the best (for a game where the highest + wins). Reaching the best makes its chip glow; passing it turns the line into + a rainbow with a NEW BEST tag and a burst of sparks, once a round. A round + that beats a saved best ends with **New best!** on the end screen, and Mini + golf, which only knows at the end, fires its sparks then. Reduced motion keeps + the colors and drops the movement. +- **Private.** Best scores, Snake's surprises found, Light Trails' furthest arena, Bug Hunt's finds, Sunset Drive's roads found, Stack Deploy's highest floor, Bumper Ring's furthest arena, Rapids Run's furthest dam, Hot Potato's furthest venue, Crossing Rush's furthest zone, Bounce Road's furthest stage, the most Ghoul Rush stages cleared in a run, Flock Dash's furthest stage, the last pick and the **Show Activities** switch + (User Preferences → Sounds & activities, which hides the die everywhere) are saved in + `~/.plan2code/console/looks.json`. Nothing about Activities reaches the agent + or the session. diff --git a/.readme/launcher.md b/.readme/launcher.md new file mode 100644 index 0000000..92e1ecc --- /dev/null +++ b/.readme/launcher.md @@ -0,0 +1,43 @@ +# The plan2code command and other agents + +The command-line side of Plan2Code: what `plan2code` does when you run it, and how to use an agent other than Claude Code, Devin or Codex. Back to the [README](../README.md#install-and-start). + +## About the plan2code command + +Install (`I`) adds `plan2code` as a global command (Advanced `A` → `D` adds just the command). Run it from any project and the Plan2Code +dashboard opens right there, in **Claude Code**, **Devin** or **Codex**. With more than one installed it asks which and +remembers your pick; `plan2code --cli claude`, `--cli devin` or `--cli codex` skips the question, and `--model ` +chooses the model. It works in cmd, PowerShell, Git Bash, macOS and Linux shells, and needs the +Claude Code, Devin or Codex CLI on your `PATH`. After you pick the agent it asks whether to turn its +permission prompts off (Yes by default; `--permission-mode bypassPermissions` in Claude Code, `--permission-mode bypass` +in Devin, `--dangerously-bypass-approvals-and-sandbox` in Codex, a custom agent's bypass arguments, and no question for a +custom agent that has none; for Codex the question names its sandbox, which that flag turns off too). It asks on every +launch and remembers no answer. `plan2code --keep-permissions` keeps the prompts without asking, and +`plan2code --bypass-permissions` turns them off without asking. With no terminal to ask on (a script or a pipe) the +prompts stay on unless `--bypass-permissions` is given. The installer then offers a desktop shortcut (answer `y`), +which opens a folder menu first: Choose a folder, with the project folders you opened lately under it (with none yet, it goes straight to the folder dialog). In a terminal, `plan2code` offers the same recent folders as a numbered menu. Uninstalling (`U`, or `plan2code uninstall` from any terminal) removes both. + +## Using another agent CLI, or none yet + +Plan2Code runs inside an AI coding agent CLI. With no agent it can run (none of Claude Code, +Devin or Codex, and no working custom agent), +`plan2code` opens a setup page in your browser (the web console runs it, so no agent is needed). +The page lists each agent as **Found**, **Found outside PATH** or **Not found**, with its install +commands for your system, a Copy button per command and an **Install page** link. Install one and +press **Check again**: no restart needed. An agent found outside `PATH` gets **Use it from here**, +which saves where it was found so you never touch `PATH` yourself. Below the list sit five starter +templates (GitHub Copilot CLI, OpenCode, Gemini CLI, Pi and Cursor CLI) for agents Plan2Code does not ship. +**Start with this agent** carries the run straight on in the same tab, onto the new agent's +dashboard. Naming a built-in that is missing with `--cli ` opens the same page on that agent +(a missing custom agent prints its own steps and exits 127). In the +desktop app a **Set up an agent** button opens the same page in the window and returns to the +launch card with the found agent picked. Where no page can open, such as over SSH or with no +display, `plan2code` prints the install commands and install pages and exits with code 127. + +Once an agent is running, to use a different agent CLI, open the web console's **User Preferences → Agents & models** and add it: a name, the +command, and (optionally) its arguments, the start prompt, arguments for skipping permission prompts, and +how it takes a model. Custom agents are saved in `~/.plan2code/agents.json` and used by both the +`plan2code` command (listed after the built-ins; `--cli ` picks one) and the desktop app's picker. The +`/plan2code` start prompt only does something in an agent that loads the installed Plan2Code skills; for +any other, leave the start prompt blank and start a skill yourself. Details in +[web-console.md](web-console.md#agents--models). diff --git a/.readme/metrics.md b/.readme/metrics.md index ef47279..4794aa6 100644 --- a/.readme/metrics.md +++ b/.readme/metrics.md @@ -1,4 +1,4 @@ -# Metrics & Self-Improvement +# Metrics and Self-Improvement `plan2code-metrics` closes the loop on the workflow itself: it collects data from your finished specs, aggregates it across runs and prompt generations, then uses AI to diagnose which step is diff --git a/.readme/steps.md b/.readme/steps.md new file mode 100644 index 0000000..ef3aadc --- /dev/null +++ b/.readme/steps.md @@ -0,0 +1,107 @@ +# The six steps in detail + +Back to the [README](../README.md#the-workflow). Each step is its own run, and the specs on disk are the only thing carried from one to the next. +Chain a small one onto the last, or start a fresh session for a big one (rule 1). + +## 0 · Pathfinder 🧭 (optional) + +On the page: one question at a time with the options and their trade-offs, the map growing in its own +tab, and a **Write a brief** button for a printable summary. + +Some ideas are too big and unclear to plan: you can feel the shape of the work but you can't write +it as requirements, so planning would just invent the answers. Pathfinder finds the *way* to the +destination; Step 1 then walks it. + +1. **Name the destination** — one or two lines fixing what this effort is finding its way to. Settled + first, because it fixes scope. It also asks where the map should live: **local files** under + gitignored `specs/` (private, solo — the default), or **GitHub Issues** (a map issue with one + sub-issue per decision, native blocking, so your team can see and work the frontier in the tracker). +2. **Chart the map** — a breadth-first grilling surfaces the open decisions. Anything you can phrase + *sharply* becomes a question file; anything you can only sense stays listed as fog. +3. **Clear the questions one at a time** — resolving one burns off the fog behind it, graduating + whatever just became sharp into new questions. After each decision it offers a menu: take the next + question here, or start fresh — recommended after about three, to keep the agent sharp. + Ask for a **brief** at any point and you get a dated, plain-English summary of what has been + decided, what is still open, and what is next — meeting minutes, with no jargon in them. +4. **Hand off** — when nothing is left to decide, it writes a `PLAN-DRAFT` that + `/plan2code-1-plan` resumes from at Phase 4, with requirements, context, and scope already + answered. + +**Question types:** `grill` (a decision only you can make — the default) · `research` (a fact gates +it; background agents resolve these, several in parallel) · `sketch` (you need something concrete to +react to) · `legwork` (manual work that has to happen before a decision is possible). + +It never answers its own questions, and it **plans, it never builds.** When the urge to just build it +arrives, the map is done. Skip Step 0 entirely when you already know what you're building. + +**Out:** `specs//pathfinder/map.md` + `questions/` (or a `pathfinder:map` issue and its +sub-issues) → `PLAN-DRAFT-.md`. The draft is always a local file — that is what Step 1 reads. + +## 1 · Plan 🤔 + +On the page: questions in batches of up to three, the phase breakdown as a list you can reorder and +edit, and a sign-off at each stage. + +The agent works as a senior architect through seven phases, stopping for you after each: requirements +analysis · system context (reading your actual codebase) · scope assessment (a large project saves and +resumes in a fresh session) · tech stack (needs your explicit sign-off) · architecture design · +technical specification · transition decision. + +It won't finalize below **90% confidence**, and every assumption it makes is written into the draft. + +**In:** a description of the feature. **Out:** `PLAN-DRAFT-.md` + `PLAN-CONVERSATION-.md` + +## 2 · Document 📝 + +On the page: a question only where the plan leaves something open, each phase file appearing as its +own tab as it is written, and one sign-off at the end. + +The plan becomes the drawing. One `overview.md` with the phase checklist, plus one file per phase of +one-story-point tasks. Each phase is **self-contained** — an agent opening `phase-3.md` cold needs +nothing else to build it. Unit and E2E tests are excluded unless you ask for them. + +The overview also identifies the **parallel execution groups**: phases with no shared files or +dependencies, safe to run in separate agents at once. + +**In:** the `PLAN-DRAFT`. **Out:** `overview.md` + `phase-1…N.md` + +## 3 · Implement ⚡ + +On the page: a progress bar and the phase's task list ticking over as tasks land, then the completion +report and a sign-off card where you approve, ask for changes, or have the code reviewed first. + +Point it at `overview.md` and it does the rest: finds the next unchecked phase, implements every task +exactly as specified, ticks tasks off as they land, then reviews its own work against the spec and +writes a completion summary. + +One phase per conversation. It won't run tests unless the phase says to. + +**In:** `specs//overview.md`. **Out:** working code, and updated checkboxes. + +Want a second pair of eyes before you sign off? `/plan2code-3-implement-review` builds the phase the +same way, runs a focused review and the fixes you pick, and only then asks for approval. + +## Review 🔬 — optional, any time + +On the page: a few questions on scope, the findings as a report you can read in full, and a list +where you tick what gets fixed. + +An independent second opinion, not a rubber stamp. It figures out its own scope (conversation +context, your instruction, or the git diff as a fallback), analyses across 11 dimensions, and ranks +findings Critical / Warning / Suggestion. Every finding cites a file and a line, or it gets dropped — +and the review pass is read-only. It fixes things only if you ask, and verifies each fix afterwards. + +Spec-aware when `specs/` exists, and works fine without it. Most useful right after a planning or +implementation step, but there's no wrong time to run it. + +## 4 · Finalize 🧹 + +On the page: the task audit and the summary as reports, a list of the doc updates to approve, and a +confirmation before anything is archived. + +Validates every task against its phase spec, writes the summary and the list of files touched, flags +the docs that drifted (`README`, `CHANGELOG`, `AGENTS.md`), then archives the whole spec folder — +`pathfinder/` included — to `specs--completed/`. That folder is the record of *why* the code looks +like this. + +**In:** `specs//overview.md`. **Out:** archived specs. diff --git a/.readme/walkthrough.md b/.readme/walkthrough.md index a234d21..b0cdcfc 100644 --- a/.readme/walkthrough.md +++ b/.readme/walkthrough.md @@ -9,7 +9,7 @@ Each session stays short, and the specs on disk carry everything from one sessio ## Before you start -- **Node.js 18 or newer.** Check with `node --version`. No Node? Get it from [nodejs.org](https://nodejs.org/) (the LTS download), or run `winget install OpenJS.NodeJS.LTS` on Windows, `brew install node` on macOS, or use `nvm` on Linux. Then open a new terminal. +- **Node.js 18 or newer** (22 or newer if you install Claude Code with npm). Check with `node --version`. No Node? Get it from [nodejs.org](https://nodejs.org/) (the LTS download), or run `winget install OpenJS.NodeJS.LTS` on Windows, `brew install node` on macOS, or use `nvm` on Linux. Then open a new terminal. - **Git.** Check with `git --version`. The installer is fetched from GitHub with Git, and without it npm stops with `spawn git ENOENT`. No Git? Get it from [git-scm.com](https://git-scm.com/downloads), or run `winget install Git.Git` on Windows, `brew install git` on macOS, or use your package manager on Linux. Then open a new terminal. - **Start from your project.** Open your terminal in the project you want to work on (`cd` into it) before you run anything. Plan2Code works on the folder you start it in. - **Ways in.** `plan2code` (Claude Code, Devin or Codex), or type `/plan2code` in your agent (`$plan2code` in Codex). @@ -96,7 +96,7 @@ Parallel execution groups: Phase 3 and Phase 4 don't share files. ## Sessions 3 to N: Implement, one phase each Look at the session meter in the top bar first. Plan and Document add 2 points each, so after -those two the meter is at 4: **Session: getting long**, in yellow. That is the cue to close this +those two the meter is at 4: **Conversation: getting long**, in yellow. That is the cue to close this console session and start a fresh one for the build (run `plan2code` again). This is the first of the four rules: @@ -134,7 +134,7 @@ Repeat. A fresh session each time. It always finds the next open phase itself. When you reach a parallel group, it offers you the choice: open a second agent, take the other phase, and the `[/]` marks keep them from colliding. -Pick **Implement + review** instead when review should run automatically before phase approval. +Pick **Implement + Review** instead when review should run automatically before phase approval. **Review** remains available on the dashboard for an independent second opinion at any other time. --- diff --git a/.readme/web-console-internals.md b/.readme/web-console-internals.md new file mode 100644 index 0000000..4dd00d7 --- /dev/null +++ b/.readme/web-console-internals.md @@ -0,0 +1,293 @@ +# The web console, inside + +For people who change the console or drive it by hand: how it works, the security model, every route, and how to refresh the screenshots. Using the console? Read [the web console guide](web-console.md) instead. + +## How it works + +Nothing is installed. The skills ship a small zero-dependency Node server +(`references/web-console/`), and the workflow step starts it when you say yes. + +``` +agent server (detached) your browser + | | | + |-- open (binds the port, starts ->| | + | the server AND the browser) ---|---------------------------->| + |<-- http://127.0.0.1:PORT/s/TOK/ |<---- the page, first state -| + | | already inside it | + |-- post the first questions ----->|---- pushed to the page ---->| + |-- wait --seconds 240 ----------->| | + | (returns every 4 minutes with | | + | progress, then waits again) |<---- you press Send --------| + |<-- your answers -----------------| | +``` + +The server runs detached rather than as a background task of the agent, because +agent background tasks get killed at various timeouts, and that would take your +half-finished answers with them. + +**It is built to show you something fast.** A browser takes most of a second to +turn up after it is asked, so `open` binds the page's port itself and sends the +browser there before the server has even finished starting; the server takes +the port over a moment later, and the browser's request waits for it rather +than being refused. The page arrives with the session already inside it, so it +draws the real screen without asking for anything first, in your own theme and +colors from the first frame. On a Windows laptop the page is in front of you in +roughly the time the browser itself takes to open. + +**It stays up while the page is open.** The page pings it every few seconds, so +the idle clock never runs down while you are there. Close the tab and it shuts +itself down about two minutes later; it stops after four hours unless answers +you sent are still waiting for the agent, and the agent stops it outright when +the session ends. + +**The setup session hands its tab to the agent it finds.** A `setup` session is +agent-less: nothing reads its sends, so the page's agent-silence and question +rules are switched off and only the idle deadline ends it. The `plan2code` +launcher started the session and polls it for a pick; **Start with this agent** +posts an `__start` action the launcher collects, and it spawns that agent with +two environment variables, `PLAN2CODE_SETUP_ANNOUNCE` (the setup server's +address) and `PLAN2CODE_SETUP_TOKEN` (a per-session token). The new agent's own +`open` then POSTs its sign-in URL to `POST /handover` on the setup server +instead of opening a browser; the token guards the route, the setup page gets a +`move` event on its `/events` stream carrying the URL, and the tab follows it +onto the new session. Inside the desktop app none of this runs: `open` finds no +setup variables (the launcher scrubs the app ones from the setup console it +starts), the page tells the app `agent-found` instead, and the app closes the +setup page and picks the agent itself. + +That also means **the server routinely outlives the agent**. It is the agent, not +the server, that reads your answers, and the two fail separately. The page tells +the two apart: the **?** button at the top right opens Help, whose *What this +page is* tab says which halves are talking right now (and *When something +looks stuck* covers what to check), and Planny stops looking busy once +nothing is listening rather than spinning at you indefinitely. + +**State lives in three places**, and none of them is your repository (the one +exception being the note attachments the agent keeps for a spec, above): + +| Where | What | Survives | +| --- | --- | --- | +| `~/.plan2code/console/sessions//` | the questions, your draft, your answers | 30 days after the session was last touched | +| `~/.plan2code/console/sessions//workspace.json`, `ledger.ndjson`, `workspace-cursor.json` | the workspace's folders (paths, names, descriptions — never their contents), the session meter's events, and how far the agent has been told of workspace changes. Kept beside the session, so they outlive every dashboard hop | with the session | +| `~/.plan2code/console/sessions//uploads/` | images and documents attached to notes and quick questions | 30 days after the session was last touched | +| `~/.plan2code/handoffs/.md`, `.json` | each handoff's document, and which checkout, spec and skill it belongs to and whether it was picked up (`handoffs.mjs` is their one owner) | 30 days after it was last touched, picked up or not | +| `~/.plan2code/notepads/-<12 hex>/` | your notebook for one folder: `meta.json`, `tabs.json` and, per tab, `tabs//note.md` and `tabs//images/` (`notepads.mjs` is their one owner; the agent never reads them, except a tab you send) | until you delete it through Cleanup, which offers it once its newest file is 30 days old | +| `~/.plan2code/console/looks.json` | your role, theme, colors, sounds and card width, the Show Activities and Play activity sounds switches (`hideActivities`, `activitySounds`), the last activity picked (`lastActivity`), best scores (flat `activityBest` keys: `activityBestSnake`, one per Mini golf course from `activityBestGolfPirate` to `activityBestGolfFrost`, `activityBestTrails`, `activityBestBugs`, `activityBestDrive`, `activityBestStack`, `activityBestBumper`, `activityBestRapids`, `activityBestFuse`, `activityBestHop`, `activityBestBounce`, `activityBestGhoul`, `activityBestFlock`) and each game's memo (`activityMemo`: Snake's surprises found, Light Trails' furthest arena, Bug Hunt's bugs, bosses and power-ups found, Sunset Drive's roads found, Stack Deploy's highest floor, Bumper Ring's furthest arena, Rapids Run's furthest dam, Hot Potato's furthest venue, Crossing Rush's furthest zone, Bounce Road's furthest stage, Ghoul Rush's most stages cleared in a run, Flock Dash's furthest stage) | always | +| `~/.plan2code/console/subagents.json` | your Subagents switch, instruction and limit, per project folder and skill | always | +| `~/.plan2code/console/sessions//subagents-setting.json`, `subagents-cursor.json` | this session's copy of the switch, and how far the agent has been told of it | with the session | +| `~/.plan2code/agents.json` | your custom agent CLIs (User Preferences → Agents & models), read by the `plan2code` command and the desktop app | always | +| your system temp directory | the port, process id and session token | until reboot | + +Each of the workspace and meter files has exactly one writer: the server owns +`workspace.json` (the page changes it only through the `/workspace` routes +under Security), and `console.mjs` owns `ledger.ndjson` and +`workspace-cursor.json`. The meter's count is never stored; it is folded from +the ledger every time (`public/meter.js`), so a repeated `post` never counts +twice. The logic lives in small pure modules the tests import directly — +`public/workspace.js` (names, the footer label, the change lines the agent +reads), `public/meter.js` and `public/mentions.js` (the `@name` popover) — and +**Browse…** runs the per-OS picker in `picker.mjs`, copied from the +`plan2code` launcher and kept in step with it by a test. + +**Old sessions clean themselves up.** Each time a session opens, whole session +folders nobody has touched for 30 days are deleted — questions, drafts, +answers, uploads and all, paused or not — along with stray scratch files +(`.json` / `.mjs`) left at the top of `~/.plan2code/console/` for as long, and +handoffs in `~/.plan2code/handoffs/` untouched for as long, both files each. +Your `looks.json` and the `console-dir` pointer are never touched, and neither +is the session being opened. Nothing of value goes with them: the page is +never the record, `specs/` in your project is. + +**Or clean up on demand.** *User Preferences → System → Cleanup* → **Find files to +clean up** lists, with sizes, everything in `~/.plan2code/` that is not +needed: sessions untouched for 30 days (never the one you are in), anything at +the top of `~/.plan2code/console/` other than `sessions/`, `runtime/`, +`looks.json`, `workspaces.json`, `loop-setup.json`, `loop-reports.json`, +`subagents.json`, `pr-hosts.json`, `console-dir` and `update-check.json`, and +anything at the top of `~/.plan2code/` other than `console/`, `bin/`, +`launcher.json`, `install.json` (what you installed, which `plan2code update` +reads), `models.json`, `handoffs/` (old handoffs go by age, above), +`notepads/`, `app/` and `app.json` (the desktop app and its settings) and +`agents.json` (your custom agents). Each notebook whose newest file is 30 days old or +more is listed as one item, *Notebook for* its folder, and goes whole; no +automatic sweep ever removes one. It also lists each +folder in the project's `specs--completed/` whose newest file is more than 30 +days old: archived specs Finalize moved there. Only a folder git tracks is +deleted: `specs--completed/` is usually gitignored, so git couldn't restore +it, and Cleanup keeps it and says why instead. A stray is listed once +it has sat untouched for an hour, so a lock or temp file another session is +writing right now is never caught. **Delete N items** removes +only the rows you left ticked. A console running from another home +(`PLAN2CODE_CONSOLE_HOME`) only ever looks inside that home. + +--- + +## Security + +It is a local dev server that reads files in your project (never writing to it) +and keeps its own state in your home folder, so it is built to be boring about +this: + +- Bound to `127.0.0.1` only, never `0.0.0.0`. Not reachable from your network. +- A `Host` header allow-list, which is what stops a website you happen to be + visiting from talking to it through a DNS rebinding trick. +- A 128-bit token in the link, swapped for an `HttpOnly; SameSite=Strict` cookie + on first load so it leaves your address bar, your history and any screenshot. +- A strict Content Security Policy with no inline script allowed. +- Markdown written by the agent is turned into page elements directly and never + into an HTML string, so a document that quotes a hostile README cannot run + anything. It shows up as text, which is what it is. +- Uploads are named by the server (`.jpg`, or `.` with the + extension taken from the allow-list, via `crypto.randomUUID()`), never by the + file name you sent, and live only under the session's own `uploads/`. The + server checks the bytes: a JPEG header for images (4 MB cap), and for + documents a `%PDF-` header or strict UTF-8 with no NUL byte (10 MB cap). + Documents are served back only under a fixed type (`application/pdf`, or + `text/plain` for text and code) with `nosniff` (and `sandbox` on text), so + the Sent box can link them. A send may only point at + uploads inside that session's `uploads/`, images in `images` and documents + in `files`. + +### Routes + +The upload routes, the send, the overview and handoff reads, the workspace and the notebook. Like every page route, they are on `127.0.0.1` +behind the session cookie, and the ones that write also check the request's +origin. + +| Route | Does | +| --- | --- | +| `POST /upload` | Raw bytes, original name in `x-p2c-name`. `Content-Type: image/jpeg`: writes `uploads/.jpg` and answers `{ ok, id, kind: "image", path, url, name, size }`; not a JPEG → 415, over 4 MB → 413. `Content-Type: application/octet-stream`: a document, its extension from the name's allow-listed extension; writes `uploads/.` and answers `{ ok, id, kind: "file", path, name, size }` with no `url`; not an allowed extension or contents that do not match → 415 `type`, over 10 MB → 413. Any other content type → 415. | +| `GET /uploads/.` | Serves an upload: an image as `image/jpeg` (the thumbnail after a reload), a document as `application/pdf` or `text/plain; charset=utf-8` with `nosniff` and, on text, `Content-Security-Policy: sandbox`. Only `.` names under `uploads/`; anything else is 404. | +| `DELETE /uploads/.` | Deletes an image or document removed before sending. 204, or 404 if it is not there. | +| `POST /submit` | The Send. A note may carry `images` and `files`, each `[{ path, name }]`: at most 5 together, images in `images` and documents in `files`, every path inside this session's `uploads/`, otherwise 400. | +| `POST /chat` | A Quick question `{ text, about?, images?, files?, conversation }`, or `{ reset: true, conversation }` for New conversation. Appended to the session's `chat.ndjson`. 400 `too-long` (over 4,000 characters), `image`, `file` or `bad`; 409 `offline`, `stale` or `limit` (10 per conversation). Never refused because a card send is still uncollected. | +| `POST /chat/decision` | Approve or Decline on an edit the agent proposed: `{ re, decision, text?, conversation }`. Once per proposal; does not count toward the 10. | +| `GET /overview?spec=specs/[&file=map\|draft]` | The Overview tab's read of `/overview.md` (or, with `file=`, the Map tab's `pathfinder/map.md` or the Plan draft tab's live `PLAN-DRAFT-*.md`), as `text/markdown` with `cache-control: no-store` and the file's spec-relative name, URL-encoded, in `x-spec-file`. A missing file is a 204. On the dashboard `spec` must be one of the scanned specs; elsewhere the session's own spec is used. The file's real path must stay inside the project, so `../`, absolute paths and symlinks pointing out all get the same 204 as a missing file, as does an unscanned `spec` or an unknown `file`. | +| `GET /agents-doc[?file=]` | The Dashboard's AGENTS.md tab: `AGENTS.md` (the default) or one `.agents-docs/.md`, as `text/markdown` with `cache-control: no-store`. A dashboard only; any other file name, a missing file or a path that leaves the project is a 204. | +| `GET /prototypes?spec=specs/` | The Prototypes tab's list: `{ files: [{ name, kind }] }` (`kind` `md` or `html`) for the files directly in `/prototypes/`, or a 204 when there are none. The spec is chosen as for `/overview`. | +| `GET /prototype?spec=specs/&name=.md` | One `.md` from `/prototypes/`, as `text/markdown` with `cache-control: no-store`; any other name, a missing file or a path that leaves the folder is a 204. | +| `POST /open-prototype` | `{ spec, name }`: opens one `.html` from `/prototypes/` in the person's default browser. 404 for any other name, 500 when no browser could start. | +| `GET /handoff?id=` | *Read it all*: the handoff's `.md` from `~/.plan2code/handoffs/`, as `text/markdown` with `cache-control: no-store`. A dashboard only, and only an id its own scan listed: a used, unknown or malformed id is 404. | +| `POST /learning/pause` | Pause for me: `{ paused: boolean }` (origin-checked; anything else is 400 `bad-request`, and 409 `not-on` unless Learning is On or Paused for you). Writes the personal pause on this machine only (`pause.json` under `~/.plan2code/learning//`), the server's only write for Learning, and repaints the row with no agent. | +| `GET /learning/state` | The Learning row's state worked out now, `{ state, pausedSince, waiting, oldestDays }` (`{}` when the project's settings file is from a format it cannot read), with `cache-control: no-store`. | +| `GET /learning/lessons` | Open the lessons, read only: `{ files: [{ name, title, text }] }` from the project's lessons (`.plan2code/lessons/`, saved with the repository), `general.md` first, then the other `.md` files in name order (plain files only, at most 100 of 512 KB each), with `cache-control: no-store`. | +| `GET /workspace` | The Workspace dialog's list: folders, `missing`, `remote` and the agent's folder `issues`. `?check=1` re-checks every folder on disk first. | +| `POST /workspace/add` | `{ path, name?, description? }`. The path is resolved against the folder the session started in (`~` expanded) and must be a folder: 400 `not-a-folder`, `duplicate` (with its `name`; compared case-insensitively on Windows and macOS), `bad-name`, or `name-taken` with a `suggest`. Answers the new entry, `nested: true` when it sits inside another folder in the list. | +| `POST /workspace/edit` | `{ id, name?, description? }`. Renames or re-describes one folder: 400 `bad-name` / `name-taken`, 404 `unknown`. | +| `POST /workspace/remove` | `{ id }`. 400 `original` for the folder the session started in, 404 `unknown`. | +| `POST /workspace/browse` | Opens the system folder picker and answers `{ path }` or `{ cancelled: true }`; never adds anything itself. 409 `busy` while one is open, 404 `no-picker` when the session looks remote or no picker exists. | +| `GET /notepad[?tab=]` | The notepad for the folder this session runs in: `{ tabs: [{ id, name, sent? }], last, tab: { id, text, savedAt, images: [{ id, url, thumb }] } | null }`, with the tab's `text`, `savedAt` and `images` repeated at the top. Without `tab` it answers the last one used; 404 `no-such-tab` for an id it does not have. A notepad in the first shape answers one virtual tab, Notes. Reading never creates or moves a file. | +| `POST /notepad/text?tab=` | `{ text }`. Saves that tab's `note.md` and answers `{ ok, savedAt }`; 400 `bad`, 404 `no-such-tab`, 413 `too-long` (over 1 MB). | +| `POST /notepad/image?tab=` | Raw `image/jpeg` (the page re-encodes every picture first). Writes the tab's `images/.jpg` and answers `{ ok, id, url }`; 415 `not-jpeg`, 413 `too-large` (over 4 MB), 409 `too-many` (200 pictures in the tab). | +| `POST /notepad/thumb?id=&tab=` | Raw `image/jpeg`: that picture's thumbnail. 404 `not-found` or `no-such-tab`, 415 `not-jpeg`, 413 `too-large`. | +| `POST /notepad/image/delete?tab=` | `{ id }`. Deletes a picture and its thumbnail; 404 `not-found` or `no-such-tab`. | +| `POST /notepad/tab` | `{ name }`. Makes a tab, which becomes the last one used, and answers `{ ok, id, name }`; 400 `bad-name`, 409 `duplicate-name` (any case) or `too-many-tabs` (20). | +| `POST /notepad/tab/rename` | `{ id, name }`. Answers `{ ok, id, name }`; 400 `bad-name`, 404 `no-such-tab`, 409 `duplicate-name`. | +| `POST /notepad/tab/delete` | `{ id }`. Removes the tab from the index, then its folder (text and pictures); 404 `no-such-tab`. | +| `POST /notepad/tab/order` | `{ order: [id] }`, every current id exactly once; 400 `bad` otherwise. | +| `POST /notepad/tab/last` | `{ id }`. Remembers the open tab; 404 `no-such-tab`. | +| `POST /notepad/tab/sent` | `{ id, workflow, spec? }`. Records that the tab was sent (`workflow` one of `pathfinder`, `plan`, `quick-task`, `revise-plan`, `diagnose`, `ui-prototype`; `spec` like `specs/`) as `sent: { workflow, spec?, at }` on its `tabs.json` entry, shown back in `GET /notepad`'s `tabs`. The page posts it only after the Send that carried the filled box; 400 `bad-sent`, 404 `no-such-tab`. | +| `GET /notepad/images//.jpg`, `.thumb.jpg` | Serves a picture or its thumbnail as `image/jpeg`, only by a tab id and a UUID name, a regular file (never a link) whose real path stays inside `~/.plan2code/notepads/`; anything else is 404. | +| `POST /subagents` | `{ on, instruction, max }` (`instruction: null` for the shipped default). Saves the switch for this project and skill and answers `{ ok, setting }`; 400 `not-offered` on a skill without the switch, `bad`, `too-long` (over 2,000 characters) or `max` (outside 1 to 20). | +| `GET /agents` | The agents view's data: your custom agents and the shipped built-ins and templates, each entry merged with its lookup result `{ state, path, where, folder }`: `state` is `found` (on PATH), `outside` (saved Windows PATH, npm's global folder or an install folder) or `missing`, and `where` says which search found it. Built-ins carry their `install` lines for the server's OS only. | +| `POST /agents` | `{ agents, replace? }`. Saves the custom-agent list to `~/.plan2code/agents.json`, validated first (400 `{ error, index, field }`); 409 while the file holds entries `GET /agents` could not read, unless `replace: true`. | +| `POST /agents/test` | `{ command }`. Where a command would run from (`{ found, path }`), for the form's Test button; never runs it. | +| `POST /agents/use-path` | `{ id }`. "Use it from here": saves the location the lookup found off PATH as the agent's `command` (a built-in becomes a new custom entry; 404 unknown, 409 `not-found`). | +| `POST /handover` | Setup sessions only, and only with the session's setup token in `x-plan2code-token`: the new agent's `open` posts `{ url }` here, the server broadcasts a `move` event with it and the setup tab follows. 409 `moved` once it has happened. | + +## For maintainers + +| | | +| --- | --- | +| Source | `src/web-console/` (one row per file in the files tables of the `.agents-docs/AGENTS-architecture-*.md` area files; a test keeps it complete) | +| Ships as | `skills//references/web-console/` | +| Wiring | one `additionalReferences` entry per skill in `install.js`; the dashboard's menu lives in `public/skills.js` (each entry's `card`; `SKILL_CATALOG` in `public/answers.js` is a lookup on it) | +| Agent contract | a card, `src/web-console/console.md` (read once), plus pointers: the console names a topic file (`console-*.md`, `notes/.md`, `building.md` / `building-review.md`) in its own `read` output, once per session per topic, when its moment comes; `console.mjs help ` prints any of them. A `stop` with no `finish`, or a `finish` while `stopWarning` is set, is refused with the fix; `stop --session --force` ends a dead page or an abandoned session anyway. Patches are one line, with lettered options and the console's own defaults filled in; a refused patch names the field and the fix. Byte budgets keep the card, the notes and a sample session's outputs from growing back (`scripts/test-console-wire-budgets.mjs`) | +| Tests | `node --test scripts/test-web-console-*.mjs` (split by area, shared setup in `scripts/web-console-test-helpers.mjs`), also run by `npm test` | +| Start-up benchmark | `node scripts/bench-web-console.mjs` (needs a local Chrome or Edge for the paint columns, driven through `playwright-core` from `npm install`; `--browser-delay 900` models a real browser launch, `--roundtrip` times Send→agent and post→page) | +| Screenshots | `node scripts/capture-screenshots.mjs` (needs a local Chrome or Edge, driven through `playwright-core` from `npm install`; `PLAN2CODE_TEST_BROWSER=chrome|msedge` forces one) | +| Dependencies | none at runtime. `marked` 15.0.7 (MIT) is vendored for its lexer only, and CodeMirror 6 (MIT) for the notebook's editor as one bundled file, `public/vendor/codemirror.esm.js`, made by the dev-only `node scripts/vendor-codemirror.mjs` from a pinned lock (about 500 KB, loaded only when the Notebook is first opened); the page's policy blocks the ` +
+
+
Plan2Code
+

Plan it.Approve it.Let it build.

+

Plan, approve and build with your AI agent, on one page.

+
+ diff --git a/version.json b/version.json index 0ca717c..9ec7f0e 100644 --- a/version.json +++ b/version.json @@ -1,7 +1,7 @@ { "name": "Plan2Code", - "version": "3.1.0", - "description": "A structured 4-step workflow methodology for AI-assisted software development", + "version": "3.1.1", + "description": "A structured workflow of six steps (Pathfinder, Plan, Document, Implement, Review, Finalize) for AI-assisted software development", "keywords": [ "ai", "workflow", @@ -11,12 +11,12 @@ "plan" ], "author": "Justin Parker", - "license": "MIT", + "license": "Apache-2.0", "repository": { "type": "git", "url": "https://github.com/jparkerweb/plan2code" }, "homepage": "https://github.com/jparkerweb/plan2code", - "releaseDate": "2026-11-15", + "releaseDate": "2026-11-17", "mode": "utility" }