texas — Conventions, Contract, and Operating Model

Multi-tasking agent / wrangler of time management. A Unix-style launcher that spreads context across terminals while preserving identity.

This document defines what texas is, what it is not, and the conventions that govern its implementation and evolution.

1. Mental Model (Read This First)

Think of texas as a binary, not a script.

• Same name
• Same interface
• Same meaning
• Multiple implementations

Just like ls, sed, or tar:

• There is no single canonical implementation
• Behavior is defined by contract, not code
• Differences exist behind a stable interface

From the top level of the repo, texas should feel like:

“One command, many environments, zero surprises.”

2. Core Use Case (Non-Negotiable)

texas <dir> [subdir]

What it does (only this, nothing more):

1. Opens one terminal per subdirectory of <dir> (or just [subdir] if specified).
2. For each terminal:
   • Establishes visual identity via .themefile
   • Establishes context identity via NAMESPACE
   • Drops the user into an interactive shell

That’s it.

• No tmux.
• No editors.
• No orchestration.
• No automation beyond identity + launch.

Anything beyond this belongs above texas, not inside it.

3. Identity Model

3.1 .themefile (Visual Identity)

Purpose: Give each repo/worktree a persistent, portable color identity.

Rules:

• .themefile lives at the repo/worktree top level (same level as .git).

• Contents:

  #RRGGBB
  

• If missing or invalid:

  • Generate a random color
  • Persist it

• Once created:

  • Never change it automatically

Why this matters:

• Survives symlinks, worktrees, repo moves, lifecycle reshuffles
• Two terminals pointing at the same worktree must look the same
• Two different worktrees must never fight over identity

This is repo identity, not lifecycle identity.

3.2 NAMESPACE (Context Identity)

Purpose: Tell your eyes and hands where you are operating, not what the repo is.

Default convention:

NAMESPACE="<basename(dir)>/<basename(subdir)>"

Examples:

• texas srv/prod api → prod/api
• texas srv/triage v2 → triage/v2

Key rule: Namespace reflects placement, not repo name.

This avoids guessing when:

• The same repo exists in multiple lifecycle stages
• Multiple versions/worktrees are active
• Names are reused intentionally

Important: NAMESPACE is contextual, not persistent. It is derived at launch time, not stored.

4. Directory & Lifecycle Conventions

4.1 Lifecycle Directories

The repo does not enforce lifecycle semantics, but it assumes this common pattern:

srv/
  prod/
  triage/
  wip/
  dev/

Each lifecycle directory contains modules, which may be real directories, symlinks to worktrees, or versioned subdirectories (v1, v2, etc.). texas must not care which you choose. If it is a directory (or symlink to one), it is a module.

4.2 Versioning by Directory (Recommended, Not Required)

You may split versions like this:

prod/
  v1/
    api/
  v2/
    api/

This is encouraged because it avoids collisions, makes NAMESPACE self-describing, and works naturally with worktrees. But texas must not require this.

5. OS & Platform Conventions (Critical)

5.1 No OS Branching in Core Logic

Forbidden:

if [[ "$(uname)" == "Darwin" ]]; then ...

This rots.

5.2 OSes Are Treated Like Binaries

From the top level of the repo, different OS realizations are conceptually equivalent to:

bin/
  texas-linux
  texas-darwin
  texas-bsd

…but hidden behind the same interface.

Rule:

• Differences are isolated behind capability tags
• Never behind explicit OS checks

6. Tag System (Capability-Driven Design)

Tags are conceptual capabilities, not files or flags.

Required tags:

• terminal.open: Can open a new terminal running a command
• git.root: Can resolve repo/worktree top level
• color.random: Can generate entropy for #RRGGBB
• theme.apply: Can apply theme via hooks

Each implementation may realize these tags differently.

Example (conceptual):

terminal.open(cmd)

Might be realized by:

• gnome-terminal
• kitty
• wezterm
• xterm
• Terminal.app wrapper

But the contract stays the same.

7. Terminal Launch Contract

When terminal.open is invoked, the new terminal must:

1. cd into the module directory
2. Export:
   • NAMESPACE
   • THEMEFILE
   • COLOR
3. Source shell rc files if needed to load hooks
4. Apply theme:
   • load_themefile "$THEMEFILE" if available
   • else apply_theme_vars "$COLOR" if available
5. Drop into an interactive shell

Anything less breaks the contract.

8. Hooks & Extensibility

Supported hooks (optional):

• load_themefile <path>: Preferred theme application
• apply_theme_vars <color>: Fallback

texas must detect hooks, never require them, and never fail if they are missing.

9. Git & Worktree Semantics

Git awareness:

• Git is optional
• If present: use git rev-parse --show-toplevel
• If absent: treat module directory as top level

Worktrees are first-class citizens.

• .themefile belongs to the worktree
• Not the bare repo
• Not the lifecycle directory

This makes multiple worktrees safe, symlinks safe, and parallel work safe.

10. PR & Branching Conventions

Branching:

• Feature branches are encouraged
• Behavior-changing PRs must update docs
• No “silent semantic changes”

Pull requests touching texas should answer:

1. Does this change the contract?
2. Does this introduce a new tag?
3. Does this violate namespace truth, repo identity, or capability isolation?

If yes → docs first, code second.

11. What texas Is NOT

Explicit non-goals:

• Project manager
• Task runner
• tmux wrapper
• Editor launcher
• Dependency resolver
• CI tool

Those live above texas. texas is a primitive.

12. Summary (The One Paragraph)

texas is a Unix-style launcher that fans out terminal sessions across a directory of modules while preserving visual identity (via a persistent .themefile at repo top level) and context identity (via a derived NAMESPACE). It avoids OS branching by isolating platform differences behind capability tags, treats operating systems like interchangeable binaries, and refuses to guess repo semantics. Its power comes from doing one small thing correctly and consistently, so higher-level workflows can be built on top without friction.