agentstack

Shared AI agent guidance and workflow tooling for projects. Add this repo as a git submodule at .agentstack/ so every new project starts with the same agent workflows, conventions, and session scripts.

What you get

Path (in this repo)	Purpose
docs/	Generic agent docs: workflow, ask, conventions, security, terminal tips, etc.
scripts/	ask.sh CLI, init_grok_session.sh, init_claude_session.sh, git hooks
templates/	Stubs for wiring a new project (.agentstack.env, CLAUDE.md, project docs/)

When mounted as a submodule in a host project:

Host path	Purpose
.agentstack/	This repo (submodule)
.agentstack/docs/	Generic guidance
docs/	Project-specific guidance

Quick start (new project)

From an existing project repo (e.g. wrtstack):

# 1. Add submodule
git submodule add git@github.com:farscapian/agentstack.git .agentstack

# 2. Run the wiring script (creates .agentstack.env, wrapper scripts, stubs)
./.agentstack/scripts/add-to-project.sh

# 3. Edit .agentstack.env and CLAUDE.md for your project
# 4. Commit submodule + new files
git add .agentstack .agentstack.env CLAUDE.md docs scripts .githooks
git commit -m "Add agentstack submodule and AI guidance"

Or clone with submodules:

git clone --recurse-submodules git@github.com:farscapian/<your-project>.git

Agent session workflow (summary)

1. New session -- grok/claude create a worktree under their own root (~/.grok/worktrees, ~/.claude/worktrees); make it ask-aware with ask adopt <path> (or ask discover --adopt)
2. Work -- agent edits only its session worktree, never the canonical local repo
3. Handoff -- human runs ask sync (or ask up) from ~/.bash_aliases; agents never git push origin

Full details: docs/workflow.md and docs/ask.md.

ask CLI (human-side handoff)

Entry point: scripts/ask.sh. After scripts/install-shell-aliases.sh, your shell defines a thin ask() wrapper. Pwd-oriented: cd to the canonical repo or a session clone, then run a command.

Handoff

Command	Description
ask / ask help	Show main help menu
ask sync	Local-sync session clone -> canonical (pick farthest ahead; auto-sync behind clones)
ask sync -f	Same, but ignore session clones initialized before the last ask
ask sync --stashes	Opt in: prompt to move canonical stashes into the session clone
ask sync all	Align every session clone behind canonical (--dry-run to preview)
ask up	ask sync, then git push origin main
ask up -f	ask sync -f, then push
ask up --stashes	ask sync --stashes, then push

Session clones

Command	Description
ask adopt [PATH]	Make an agent-created worktree ask-aware (write env + align); --grok/--claude force the agent
ask discover [--adopt]	List agent worktrees for this repo + adopt status; --adopt provisions unadopted ones
ask list	List session worktrees for this project (by origin URL)
ask status	Ahead/behind origin/main for canonical and each session clone
ask info <n>	Plain-language summary for session #n (from ask status; includes dirty-work analysis)

| ask drop | Archive all session clones except #1 (collapse into one) | | ask drop <n> | Archive and remove session clone #n (index from ask list) | | ask drop <src> [dest] | From a consumer session clone: copy generic work into agentstack |

Trim and publish

Command	Description
ask up trim	Roll dirty work into kept clones, archive stale session clones
ask up trim --dry-run	Print keep/prune/rollover plan only
ask up trim --yes	Skip confirmation prompt
ask up trim --keep-latest N	Keep N most-recently-modified clones (default 1)
ask up trim --no-rollover	Keep dirty older clones instead of rolling work over
ask publish	ask up agentstack, then bump .agentstack in consumers, auto-trim clones

Help

Main menu (ask / ask help) lists direct subcommands only. Detailed help for each command (and nested topics like sync all, up trim) lives in docs/help/*.txt. See docs/cli-help.md.

ask help
ask help sync
ask sync help
ask up trim help
ask help publish

See docs/ask.md for guards, trim/archive rules, and the ask publish bump protocol.

Starting a session (template or host project)

Let the agent create its worktree in its own default location, then adopt it:

# 1. Create a worktree the agent's way (under ~/.grok/worktrees or ~/.claude/worktrees)
grok --worktree          # or Claude Code's worktree feature

# 2. From the canonical repo, make it ask-aware:
cd ~/Sync/mini_projects/agentstack   # or your host project canonical
ask discover --adopt     # or: ask adopt ~/.claude/worktrees/<name>

ask adopt writes .agentstack.env (derived from canonical), aligns the worktree to canonical main, and readies it for agent work. Works for the agentstack template repo itself (no .agentstack.env at canonical).

Branding

Always lowercase agentstack in docs and messages (never Agent Start Stack / AgentStack) -- except when naming the command-line utility itself, styled aGENTsTACk (e.g. "the aGENTsTACk handoff CLI").

Maintenance

• CLI changes: edit scripts/lib/ask-aliases.sh, then re-run scripts/install-shell-aliases.sh and source ~/.bashrc
• Generic workflow changes belong here; bump the submodule in host projects when updated
• Project-specific gotchas, CLI, architecture stay in each host project's docs/