Skip to content

Setup and layout

Workspace structure

The workspace root is an organization folder, not a git repo. Each top-level directory is an independent repository with its own dependencies and deploy lifecycle. Shared, cross-repo tooling lives in hq/.

frontstory/                     # workspace root (not a repo)
├── CLAUDE.md                   # shared conventions + loads the rules below
├── .claude/                    # AI tooling (its own git repo)
│   ├── CLAUDE.md
│   ├── commands/               # slash commands  -> Commands reference
│   ├── skills/                 # skills + role personas -> Skills and agents
│   ├── rules/                  # auto-applying rules -> Auto-applying rules
│   └── <repo>/CLAUDE.md        # per-repo AI rules (flat, one folder per repo)
├── hq/                         # shared tooling: jira.cli, deploy, context_cache, infra, docs
├── jira-mock/                  # mock Jira backend (SKYN-* tickets)
├── specs/                      # attached specs (specs/AISD-N.md)
├── tasks/                      # per-task working artifacts (tasks/AISD-N/)
└── <repo>/ ...                 # the org's service repositories

.claude/ is its own repo

The workspace root is not a git repository; .claude/ is. Run git against it explicitly (git -C .claude ...). Editors that don't track .claude/ or .cursor/ can silently drop changes -- commit them in-flow.

CLAUDE.md and rule loading

The workspace CLAUDE.md is the primary source of truth (it overrides per-repo CLAUDE.md files). It references the files in .claude/rules/, so Claude Code loads each rule into context on every session in this workspace. That is how behaviors like model routing, the context cache, deploy targets, and the task pipeline apply without being explicitly invoked. See Auto-applying rules.

Python environments

  • AI-pipeline tooling runs from hq/.venv -- one shared hq/requirements.txt provides boto3, requests, fastapi, pymysql, etc. Invoke tooling as hq/.venv/bin/python -m hq.<module>.
  • Project smoke tests run from that project's own .venv.
  • Docs toolchains are separate (requirements-docs.txt per docs package), installed into a throwaway venv -- never into hq/.venv.

Common entry points:

hq/.venv/bin/python -m hq.jira.cli <cmd>          # Jira operations
hq/.venv/bin/python -m hq.deploy check <repo> --env stage
hq/.venv/bin/python -m hq.context_cache search "<keyword>"

Per-repo AI rules

Repository-specific guidance lives at .claude/<repo>/CLAUDE.md (a flat one-folder-per-repo convention, not under .claude/projects/). The project-skills skill routes each repo to the persona + task-skills it should use. See Skills and agents.

Credentials

Secrets come from AWS Secrets Manager via fs_config.get_secret(...); never hardcode credentials. Environment selection is via ENVIRONMENT (stg / prd / local). Deploy hosts in private subnets are reached through a bastion (see Auto-applying rules).