Hour One in a New Repo: Pin Commands AI Must Not Invent

You pin real commands before you prompt anything.
Hour one is evidence work, not coding work.
A junior earns trust by recording what already runs.

The failure you should refuse

You clone a repo and feel behind.
You paste the README into a chat window.
The model invents a start script you never ran.

That invented script can still look very professional.
It may also skip the team's real test gate.
You then open a PR that nobody can reproduce.

Core rule for your first hour

AI may explain a command you already executed.
AI may not invent a new start or test path.
You write that strict rule into GOLDEN_PATH.md.

Keep the pin file short and boring.
Dates, SHAs, and exact command lines belong there.
Opinions and architecture lectures do not belong.

What you will produce

You will leave three artifacts after sixty minutes.
None of those three artifacts change product behavior.

1. GOLDEN_PATH.md with commands you actually ran.
2. scripts/pin-golden-path.sh that records facts.
3. A first PR that only adds those files.

This is a proposal workflow for a new clone.
Label it as unexecuted until you run it locally.
Do not claim a metric you did not measure.

Step 1: Clone and freeze your hands

Open a clean directory for the new job.
Clone with the team's documented default branch.

git clone [e-mail]:example/team-app.git
cd team-app
git rev-parse --abbrev-ref HEAD
git rev-parse HEAD
git status --porcelain

Confirm that the working tree is empty.
Do not create a feature branch yet.
You still have nothing safe to change.

Step 2: List candidate commands without AI

Read the files that humans already committed.
Ignore generated lockfile noise while you scan.

ls -1 Makefile package.json pyproject.toml go.mod compose.yaml 2>/dev/null
sed -n '1,80p' README.md

If package.json exists, print the scripts only.

python3 - <<'PY'
import json, pathlib
p = pathlib.Path("package.json")
if p.exists():
    data = json.loads(p.read_text())
    for name, cmd in sorted((data.get("scripts") or {}).items()):
        print(f"{name}: {cmd}")
PY

If a Makefile exists, print target names.

awk -F: '/^[a-zA-Z0-9][^$#\/\t=]*:([^=]|$)/ {print $1}' Makefile | head

Write the candidates on paper or in notes.
Do not ask a model to set the project up.

Step 3: Run one command with your shell

Pick the smallest test or lint target.
Run it once and capture the exit code.

mkdir -p .onboarding
TEST_CMD='npm test -- --watchAll=false'
# Replace TEST_CMD with the real candidate.
{
  echo "cmd: $TEST_CMD"
  echo "started: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
}
set +e
bash -lc "$TEST_CMD" | tee .onboarding/test.out
echo "exit: $?" | tee .onboarding/test.code
set -e

If the command fails, you should stop.
A failing golden path is still evidence.
You now know the repo's current truth.

Do not fix the failure with a generated patch.
Your first hour is not a bug-fix hour.
Ask a human if the command itself is wrong.

Step 4: Write GOLDEN_PATH.md from evidence

Create the file from the log, not memory.

# GOLDEN_PATH

Pinned: 2026-09-07
Commit: REPLACE_WITH_SHA
Branch: main
Operator: junior clone, hour one

## Commands I ran

- install: `npm ci`
- test: `npm test -- --watchAll=false`
- exit: 0

## Commands I did not run

- start
- migrate
- docker compose

## AI rules

- Explain these commands only.
- Do not invent a new package manager.
- Do not add undocumented Make targets.
- Do not change CI YAML in the first PR.

Fill SHA and exit codes from your terminal.
Delete any command you did not execute.
Unknown start paths stay in the skipped list.

Step 5: Add a pin script for the next junior

Save this file as scripts/pin-golden-path.sh.
It is a template you must review first.

#!/usr/bin/env bash
set -euo pipefail

root="$(git rev-parse --show-toplevel)"
cd "$root"
mkdir -p .onboarding

sha="$(git rev-parse HEAD)"
branch="$(git rev-parse --abbrev-ref HEAD)"
when="$(date -u +%Y-%m-%dT%H:%M:%SZ)"

cmd="${1:-}"
if [[ -z "$cmd" ]]; then
  echo "usage: scripts/pin-golden-path.sh 'exact command'" >&2
  exit 2
fi

set +e
bash -lc "$cmd" | tee .onboarding/last.out
code=$?
set -e
echo "$code" > .onboarding/last.code

cat > GOLDEN_PATH.md <<EOF
# GOLDEN_PATH

Pinned: ${when}
Commit: ${sha}
Branch: ${branch}

## Command I ran

\`${cmd}\`

exit: ${code}

## AI rules

- Explain this command only.
- Do not invent a parallel start path.
- Do not rewrite this file from a prompt.
EOF

echo "pinned $cmd at $sha with exit $code"

Make it executable after you read every line.

chmod +x scripts/pin-golden-path.sh

The script writes git metadata beside the command.
That pairing is the whole point here.
A model cannot fake a SHA you printed.

Step 6: Let AI explain output, not invent commands

Now you may use a coding assistant.
You paste the captured log into chat.
You do not paste a wish list.

Keep that prompt tiny and strictly local.

I ran this exact command:
npm test -- --watchAll=false
Exit code: 1
Here is the tail of .onboarding/test.out.
Explain the failure. Do not propose a new test runner.
Do not edit files. List questions for my teammate.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

MonkeyCode is an open-source assistant with free model access.
It also offers a free server option.
Point that explainer at the log after pinning.
You still run every command in your own shell.

Do not send secrets or production dumps.
The pin file should never contain tokens.
Treat the free server as a scratch explainer only.
It is not a replacement for your CI.

Step 7: First PR carries the pin, not a feature

Create a branch only for onboarding evidence.

git checkout -b onboarding/golden-path
git add GOLDEN_PATH.md scripts/pin-golden-path.sh
git status
git diff --cached

Write a PR body that names the command.

## Why

Hour-one pin for juniors. No product change.

## Evidence

- Command: `npm test -- --watchAll=false`
- SHA: REPLACE
- Exit: REPLACE

## Out of scope

- Refactors
- Dependency bumps
- CI edits

Reviewers can reproduce your first hour quickly.
They can reject the PR if the command is wrong.
That rejection is cheaper than a generated feature.

Step 8: First rollback stays inside the pin

If GOLDEN_PATH.md records the wrong command, revert it.
Do not revert teammate work to hide mistakes.

git log -- GOLDEN_PATH.md
git checkout HEAD~1 -- GOLDEN_PATH.md
git commit -m "revert: unpin incorrect hour-one command"

You practice rollback on a file you own.
You do not practice it on production config.
Save wider rollback drills for a later day.

Decision table

Use this table when a prompt feels tempting.

Situation	You do this	AI may do this
README lists five start commands	Run one. Pin it.	Explain flags on that one
Tests fail on a clean clone	Stop. Ask a human.	Restate the error lines
You do not know the package manager	Read lockfiles.	Not invent pnpm vs npm
First PR scope creeps	Close the PR.	Nothing
Log contains secrets	Redact. Do not paste.	Nothing

Print this table next to your monitor.
Hour one is a sequence of refusals.
Most refusals protect the team's real path.

A tiny test plan for the pin script

Treat these checks as a local rehearsal.
Do not run them against production hosts.

1. Run the script with no arguments and expect exit 2.
2. Run it with true and expect GOLDEN_PATH.md to appear.
3. Confirm the file contains the current git SHA.
4. Run it with false and expect a non-zero recorded exit.
5. Confirm git diff -- GOLDEN_PATH.md stays reviewable.

# Expected failure: missing command.
set +e
scripts/pin-golden-path.sh
echo "no-arg exit: $?"
set -e

# Expected success path using a harmless command.
scripts/pin-golden-path.sh 'true'
grep -q "$(git rev-parse HEAD)" GOLDEN_PATH.md

# Expected recorded failure, still a valid pin.
scripts/pin-golden-path.sh 'false'
grep -q "exit: 1" GOLDEN_PATH.md || grep -q "exit: 1" .onboarding/last.code

Stop if the SHA in the file does not match.
That mismatch means you pinned the wrong checkout.
Fix the clone before you ask any model.

Limitations

This workflow does not fix a broken build.
It does not prove production health either.
It only records what your laptop just did.

The pin can be wrong if you picked a toy script.
A demo npm script is not a test gate.
Ask the CI owner before you freeze a toy.

The bash template assumes a git checkout.
It does not handle monorepo package filters.
You must pass the package path yourself.

Free model access does not replace codeowners.
A local explainer can still hallucinate causes.
You still need a human for architecture questions.

Who should not use this

Do not use this if you already own the pipeline.
Staff engineers should document shared CI instead.
Skip it on repos that forbid extra markdown.

Do not use this if the repo is not yours.
Do not paste proprietary logs into hosted chat.
Skip the free server when the logs may contain secrets.

Do not use this as a license to delay setup.
If the team has a required bootstrap, run that.
Your pin must match the team script, not fight it.

Hour-one checklist

Work these eight items in order.
Do not skip the human ask at the end.

1. Clone the default branch with a clean tree.
2. List Makefile or package scripts by yourself.
3. Run one candidate command in your own shell.
4. Record SHA, time, command, and exit code.
5. Ask AI only to explain that captured log.
6. Open a PR that adds only the pin files.
7. Revert the pin file if the command was wrong.
8. Ask a human before any architecture change.

Close

You now have a junior hour-one loop.
Clone, run one command, pin it, then explain later.
Your first PR proves you can follow evidence.

If you want a local explainer after pinning, try MonkeyCode's free server option.
Keep the assistant out of your command path.
Your shell remains the source of truth.