# ═══════════════════════════════════════════════════════════════════════════════
# tbdflow — Exploration Agent: The Nervous Newbie
# ═══════════════════════════════════════════════════════════════════════════════
# Profile: First week on the team. Knows basic Git but has never used a
# workflow tool. Afraid of breaking things. Explores cautiously.
#
# Exploration strategy: Start with --help and --dry-run before touching
# anything real. Try the wrong thing, read the error, try again.
# ═══════════════════════════════════════════════════════════════════════════════
feature "Exploration: The Nervous Newbie's First Day"
actors: Terminal, System
settings {
timeout_seconds = 30
stop_on_failure = false
shell_path = "/bin/bash"
}
var REPO = "/tmp/explore_newbie"
var BARE = "/tmp/explore_newbie_bare.git"
# ═══════════════════════════════════════════════════════════════════════════════
# IMPLEMENTATION LAYER
# ═══════════════════════════════════════════════════════════════════════════════
task init_repo(repo, bare) {
Terminal run "rm -rf ${repo} ${bare} && mkdir -p ${repo}"
Terminal run "git init --bare ${bare}"
Terminal run "git -C ${repo} init && git -C ${repo} commit --allow-empty -m 'init'"
Terminal run "git -C ${repo} remote add origin ${bare}"
Terminal run "git -C ${repo} push -u origin main"
Terminal set_cwd "${repo}"
}
task cleanup_repo(repo, bare) {
Terminal run "rm -rf ${repo} ${bare}"
}
# ═══════════════════════════════════════════════════════════════════════════════
# EXPLORATION SCENARIOS
# ═══════════════════════════════════════════════════════════════════════════════
# ─────────────────────────────────────────────────────────────────────────────
# Journey 1: "I just got this tool, what does it do?"
#
# The newbie opens a terminal and types the tool name with no arguments.
# Then tries --help. Then explores each subcommand's help.
# Friction = anything confusing, missing, or scary in the output.
# ─────────────────────────────────────────────────────────────────────────────
scenario "Discovering what tbdflow does" {
test WhatIsThis "Type the tool name with no arguments" {
given:
Test can_start
System log "THOUGHT: What does this tool do? Let me just type the name..."
when:
Terminal run "tbdflow"
then:
# OBSERVE: Does it print something useful or just crash?
Terminal output_not_contains "panic"
Terminal output_not_contains "fatal"
}
test ReadTheManual "Try --help to understand the tool" {
given:
Test can_start
System log "THOUGHT: OK let me try --help like any CLI..."
when:
Terminal run "tbdflow --help"
then:
# FRICTION CHECK: Can I understand what this tool does in 5 seconds?
Terminal last_command succeeded
Terminal output_contains "commit"
Terminal output_contains "branch"
Terminal output_contains "sync"
}
test WhatVersion "Check what version I have" {
given:
Test can_start
System log "THOUGHT: What version did IT install for me?"
when:
Terminal run "tbdflow --version"
then:
Terminal last_command succeeded
# FRICTION CHECK: Does it show a version number?
Terminal output_contains "tbdflow"
}
test ExploreCommitHelp "Dive deeper into commit" {
given:
Test can_start
System log "THOUGHT: Commit is what I'll do most. Let me learn it."
when:
Terminal run "tbdflow commit --help"
then:
Terminal last_command succeeded
# FRICTION CHECK: Are examples shown? Types listed?
Terminal output_contains "EXAMPLES"
Terminal output_contains "feat"
Terminal output_contains "fix"
}
test ExploreBranchHelp "What about branching?" {
given:
Test can_start
System log "THOUGHT: Do I need to make branches? Let me check."
when:
Terminal run "tbdflow branch --help"
then:
Terminal last_command succeeded
Terminal output_contains "EXAMPLES"
}
test ExploreCompleteHelp "How do I finish my work?" {
given:
Test can_start
System log "THOUGHT: There's a complete command. How does merging work?"
when:
Terminal run "tbdflow complete --help"
then:
Terminal last_command succeeded
Terminal output_contains "EXAMPLES"
}
after {
System log "JOURNAL: Help text exploration complete. Did I feel oriented?"
}
}
# ─────────────────────────────────────────────────────────────────────────────
# Journey 2: "Let me try committing something safely"
#
# The newbie has a repo. They want to commit but are scared.
# They try --dry-run first. Then make mistakes. Then succeed.
# ─────────────────────────────────────────────────────────────────────────────
scenario "First commit attempt — cautious and scared" {
test Setup "Set up a safe playground" {
given:
Test can_start
System log "THOUGHT: Let me create a test repo so I don't break anything real."
when:
init_repo("${REPO}", "${BARE}")
then:
Terminal last_command succeeded
}
test CheckStatusFirst "What's the current state?" {
given:
Test has_succeeded Setup
System log "THOUGHT: Before I do anything, let me check status..."
when:
Terminal run "tbdflow status"
then:
Terminal last_command succeeded
# FRICTION CHECK: Does 'clean' mean I'm safe?
Terminal output_contains "clean"
}
test SyncBeforeAnything "Better sync first, the docs said to" {
given:
Test has_succeeded CheckStatusFirst
System log "THOUGHT: I read somewhere I should sync before working..."
when:
Terminal run "tbdflow sync"
then:
Terminal last_command succeeded
# FRICTION CHECK: Is the sync output reassuring?
Terminal output_not_contains "error"
Terminal output_not_contains "CONFLICT"
}
test MakeAChange "Create a small file to commit" {
given:
Test has_succeeded SyncBeforeAnything
System log "THOUGHT: OK, let me make a tiny change..."
when:
Terminal run "echo hello-world > greeting.txt"
then:
Terminal last_command succeeded
}
test DryRunFirst "Try dry-run before real commit — I'm scared" {
given:
Test has_succeeded MakeAChange
System log "THOUGHT: I'll use --dry-run first to see what WOULD happen..."
when:
Terminal run "tbdflow --dry-run commit -t feat -m 'add greeting'"
then:
# FRICTION CHECK: Does dry-run make me feel safe?
Terminal last_command succeeded
Terminal output_contains "DRY RUN"
}
test TryWrongTypeFirst "Oops, I typed 'feature' not 'feat'" {
given:
Test has_succeeded DryRunFirst
System log "THOUGHT: OK let me do it for real now... feature seems right."
when:
Terminal run "tbdflow commit -t feature -m 'add greeting'"
then:
# FRICTION CHECK: Is the error message helpful?
Terminal last_command failed
Terminal output_contains "not a valid"
}
test TryCapitalLetter "I naturally capitalize my sentences" {
given:
Test has_succeeded TryWrongTypeFirst
System log "THOUGHT: Oh it's feat not feature. Let me try again."
when:
Terminal run "tbdflow commit -t feat -m 'Add greeting'"
then:
# FRICTION CHECK: Does it tell me WHY it failed?
Terminal last_command failed
Terminal output_contains "capital"
}
test FinallyGetItRight "Third time's the charm" {
given:
Test has_succeeded TryCapitalLetter
System log "THOUGHT: Lowercase, no period, short. Got it."
when:
Terminal run "tbdflow commit -t feat -m 'add greeting' --no-verify"
then:
# RELIEF CHECK: Does success feel clear?
Terminal last_command succeeded
Terminal output_contains "Successfully committed"
}
test VerifyItWorked "Did my commit actually land?" {
given:
Test has_succeeded FinallyGetItRight
System log "THOUGHT: I need to verify it actually worked..."
when:
Terminal run "tbdflow sync"
then:
Terminal last_command succeeded
Terminal output_contains "add greeting"
# RELIEF CHECK: I can see my commit. I didn't break anything.
}
after {
cleanup_repo("${REPO}", "${BARE}")
System log "JOURNAL: First commit took 3 attempts. Error messages guided me."
}
}
# ─────────────────────────────────────────────────────────────────────────────
# Journey 3: "What happens if I mess up?"
#
# The newbie deliberately explores edge cases to build confidence.
# ─────────────────────────────────────────────────────────────────────────────
scenario "Exploring error boundaries to build confidence" {
test Setup "Fresh repo for error exploration" {
given:
Test can_start
System log "THOUGHT: Let me see how tbdflow handles my mistakes."
when:
init_repo("${REPO}", "${BARE}")
then:
Terminal last_command succeeded
}
test CommitWithNothing "What if I commit with no changes?" {
given:
Test has_succeeded Setup
System log "THOUGHT: What happens if I commit but nothing changed?"
when:
Terminal run "tbdflow commit -t chore -m 'empty commit' --no-verify"
then:
# FRICTION CHECK: Does it handle this gracefully?
Terminal output_not_contains "panic"
Terminal output_not_contains "fatal"
}
test CompleteOnMain "What if I try to complete while on main?" {
given:
Test has_succeeded CommitWithNothing
System log "THOUGHT: What if I accidentally run complete on main?"
when:
Terminal run "tbdflow complete -t feat -n main"
then:
# FRICTION CHECK: Does it stop me with a clear message?
Terminal last_command failed
Terminal output_not_contains "panic"
}
test BranchWithEmptyName "What if I forget the branch name?" {
given:
Test has_succeeded CompleteOnMain
System log "THOUGHT: What if I forget to pass a name?"
when:
Terminal run "tbdflow branch -t feat"
then:
# FRICTION CHECK: Clear error or cryptic crash?
Terminal last_command failed
Terminal output_not_contains "panic"
}
test MessageWithPeriod "I always end sentences with a period" {
given:
Test has_succeeded BranchWithEmptyName
System log "THOUGHT: My English teacher taught me to end with a period."
when:
Terminal run "echo oops > period.txt"
Terminal run "tbdflow commit -t fix -m 'fix the thing.'"
then:
Terminal last_command failed
# FRICTION CHECK: Does it explain the no-period rule?
Terminal output_contains "period"
}
test VeryLongMessage "I like to be descriptive" {
given:
Test has_succeeded MessageWithPeriod
System log "THOUGHT: Let me write a really detailed message..."
when:
Terminal run "tbdflow commit -t feat -m 'add a really long and detailed commit message that describes every single change I made including the refactoring and the tests'"
then:
Terminal last_command failed
# FRICTION CHECK: Does it mention the max length?
Terminal output_contains "length"
}
after {
cleanup_repo("${REPO}", "${BARE}")
System log "JOURNAL: Error handling exploration done. Every mistake was caught."
}
}