Git, Linux CLI & Team Onboarding Best Practices

Ten practices for git discipline, Linux debug literacy, and onboarding that stay honest as the agent team grows - expanded into a checklist for design reviews and quarterly health checks.

Agent products accumulate packs, pins, and tribal knowledge faster than most services. Fundamentals and docs must be maintained like production code.

How to Use This List

Walk A for version control and pack hygiene; B for operability; C for people and docs.
Tick items only when true in the repo, CI, or calendar - not as aspirations.
Pair with Onboarding a New Developer to an Agent Codebase for hire ramps and with Documenting Agent-Specific Conventions for New Team Members for the doc set.
Re-check after team growth, framework upgrades, or any SEV blamed on "process."

A - Version Control for Behavior

1. Keep prompts, tool schemas, and policies in git as reviewable packs - not only in a live admin UI.
2. Use immutable versions + pins so production points at named artifacts and rollback is a pin flip.
3. Shape branches and PRs by concern (prompt/, tools/, config/) with single-purpose diffs when possible.
4. Protect pack paths with CODEOWNERS and require humans to read behavior diffs, not only green CI.
5. Gate pack changes with validation (JSON, markers) and eval smoke or full suites on path filters.
6. Forbid conflict markers and secret material in packs via CI searches and secret scanning.

B - Linux Literacy and Operability

7. Publish a short CLI runbook for process, logs, ports, resources, and safe restart of agent workers.
8. Log pin fields on every run (prompt_version, tool_schema_version, code_sha) so shell and UI debug agree.
9. Practice rollback and kill switch on a schedule - not only during real incidents.
10. Prefer staging repro + read-only discovery before invasive prod debugging or kill -9.

C - Onboarding and Living Docs

11. Maintain an in-repo docs/agent/ map (layout, tools, prompts, git, local run, pins, evals, on-call).
12. Run a structured onboarding checklist with buddy evidence (local run, first PR, conflict drill).
13. Require doc updates in the PR template when layout or workflow changes.
14. Garden docs on a calendar and assign owners; fix gaps found by each new hire.
15. Train review of assistant-generated changes - speed without verification multiplies bad merges.

Applying These Practices in Order

Version control (1-6): cheapest insurance against unbisectable prompt history and silent schema breaks.
Operability (7-10): determines whether on-call can survive framework dashboards being wrong or down.
People/docs (11-15): determines whether the next hire ships safely without reinventing process.

If you can only adopt three items this month: (1) packs in git, (2) pins logged on runs, (3) onboarding checklist with local run.

FAQs

Why "ten practices" if there are fifteen checkboxes?

Items 1-10 are the core practices promised by the section. Items 11-15 extend them into onboarding operations so the list stays useful as headcount grows.

What is the first practice if we can only adopt one?

Stop live-editing production prompts. Put packs in git with review and a restore path.

How often should we revisit this list?

Quarterly, after each SEV with a process component, and when the team size doubles.

Do small teams need CODEOWNERS?

Yes at a light level: at least one named reviewer for pack paths. Social "just ping me" fails on vacation.

How does this relate to agent CI/CD?

These practices are the human and repo substrate under eval gates, canaries, and rollbacks in the CI/CD section.

Is Linux skill required if we are serverless?

You still need log and config literacy for the platform you run. Container and process skills transfer when the abstraction leaks.

Where should the CLI runbook live?

In-repo next to on-call docs, linked from onboarding. Out-of-band wikis drift.

How do we stop onboarding docs from rotting?

Owners, PR template checks, hire-filed gaps, and a 30-minute quarterly garden with the on-call pair.

Should product and safety share git workflow with engineering?

Share the pack PR path with clear reviewers. Do not give unreviewed prod edit rights as a shortcut.

What metrics show these practices are working?

Time to first productive PR, mean time to pin rollback, count of marker/secret CI catches, and SEVs without "unknown prompt version."

Can coding agents write our convention docs?

They can draft. Humans own accuracy, commands, and ownership fields under the same review rules as code.

How does this list interact with security best practices?

Git and onboarding enforce how secrets, tools, and prod access are taught and reviewed. Link security checklists for launch gates.

Why Agent Teams Still Need Solid Git and Linux Fundamentals - rationale
Git & Linux Basics for Agent Developers - skills ramp
Git Workflows for Prompt, Tool, and Config Changes - PR recipe
Linux CLI Essentials for Debugging Agent Processes - command sheet
Onboarding a New Developer to an Agent Codebase - hire checklist
Documenting Agent-Specific Conventions for New Team Members - doc recipe
Common Git Conflicts in Prompt and Config Files - merge playbook
CI/CD & Agent Lifecycle Best Practices - pipeline habits
Versioning Prompts and Tool Schemas Alongside Code - pack pins

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.

Git, Linux CLI & Team Onboarding Best Practices

Ten practices for git discipline, Linux debug literacy, and onboarding that stay honest as the agent team grows - expanded into a checklist for design reviews and quarterly health checks.

Agent products accumulate packs, pins, and tribal knowledge faster than most services. Fundamentals and docs must be maintained like production code.

How to Use This List

Walk A for version control and pack hygiene; B for operability; C for people and docs.
Tick items only when true in the repo, CI, or calendar - not as aspirations.
Pair with Onboarding a New Developer to an Agent Codebase for hire ramps and with Documenting Agent-Specific Conventions for New Team Members for the doc set.
Re-check after team growth, framework upgrades, or any SEV blamed on "process."

A - Version Control for Behavior

1. Keep prompts, tool schemas, and policies in git as reviewable packs - not only in a live admin UI.
2. Use immutable versions + pins so production points at named artifacts and rollback is a pin flip.
3. Shape branches and PRs by concern (prompt/, tools/, config/) with single-purpose diffs when possible.
4. Protect pack paths with CODEOWNERS and require humans to read behavior diffs, not only green CI.
5. Gate pack changes with validation (JSON, markers) and eval smoke or full suites on path filters.
6. Forbid conflict markers and secret material in packs via CI searches and secret scanning.

B - Linux Literacy and Operability

7. Publish a short CLI runbook for process, logs, ports, resources, and safe restart of agent workers.
8. Log pin fields on every run (prompt_version, tool_schema_version, code_sha) so shell and UI debug agree.
9. Practice rollback and kill switch on a schedule - not only during real incidents.
10. Prefer staging repro + read-only discovery before invasive prod debugging or kill -9.

C - Onboarding and Living Docs

11. Maintain an in-repo docs/agent/ map (layout, tools, prompts, git, local run, pins, evals, on-call).
12. Run a structured onboarding checklist with buddy evidence (local run, first PR, conflict drill).
13. Require doc updates in the PR template when layout or workflow changes.
14. Garden docs on a calendar and assign owners; fix gaps found by each new hire.
15. Train review of assistant-generated changes - speed without verification multiplies bad merges.

Applying These Practices in Order

Version control (1-6): cheapest insurance against unbisectable prompt history and silent schema breaks.
Operability (7-10): determines whether on-call can survive framework dashboards being wrong or down.
People/docs (11-15): determines whether the next hire ships safely without reinventing process.

If you can only adopt three items this month: (1) packs in git, (2) pins logged on runs, (3) onboarding checklist with local run.

FAQs

Why "ten practices" if there are fifteen checkboxes?

Items 1-10 are the core practices promised by the section. Items 11-15 extend them into onboarding operations so the list stays useful as headcount grows.

What is the first practice if we can only adopt one?

Stop live-editing production prompts. Put packs in git with review and a restore path.

How often should we revisit this list?

Quarterly, after each SEV with a process component, and when the team size doubles.

Do small teams need CODEOWNERS?

Yes at a light level: at least one named reviewer for pack paths. Social "just ping me" fails on vacation.

How does this relate to agent CI/CD?

These practices are the human and repo substrate under eval gates, canaries, and rollbacks in the CI/CD section.

Is Linux skill required if we are serverless?

You still need log and config literacy for the platform you run. Container and process skills transfer when the abstraction leaks.

Where should the CLI runbook live?

In-repo next to on-call docs, linked from onboarding. Out-of-band wikis drift.

How do we stop onboarding docs from rotting?

Owners, PR template checks, hire-filed gaps, and a 30-minute quarterly garden with the on-call pair.

Should product and safety share git workflow with engineering?

Share the pack PR path with clear reviewers. Do not give unreviewed prod edit rights as a shortcut.

What metrics show these practices are working?

Time to first productive PR, mean time to pin rollback, count of marker/secret CI catches, and SEVs without "unknown prompt version."

Can coding agents write our convention docs?

They can draft. Humans own accuracy, commands, and ownership fields under the same review rules as code.

How does this list interact with security best practices?

Git and onboarding enforce how secrets, tools, and prod access are taught and reviewed. Link security checklists for launch gates.

Why Agent Teams Still Need Solid Git and Linux Fundamentals - rationale
Git & Linux Basics for Agent Developers - skills ramp
Git Workflows for Prompt, Tool, and Config Changes - PR recipe
Linux CLI Essentials for Debugging Agent Processes - command sheet
Onboarding a New Developer to an Agent Codebase - hire checklist
Documenting Agent-Specific Conventions for New Team Members - doc recipe
Common Git Conflicts in Prompt and Config Files - merge playbook
CI/CD & Agent Lifecycle Best Practices - pipeline habits
Versioning Prompts and Tool Schemas Alongside Code - pack pins

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.

Git, Linux CLI & Team Onboarding Best Practices

Search Documentation

Git, Linux CLI & Team Onboarding Best Practices