briefing

Files (3)

• README.md
• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# `/briefing` — Adaptive project orientation

## Invocation boundary

This skill is manual-only. Run it only when the user explicitly invokes `/briefing`, `$briefing`, or asks to run the briefing skill. A mention while discussing or editing the skill is not an invocation. If a reminder or automatic skill selector loads it without that request, stop before source discovery and answer the user's actual question within the active task.

This skill produces a structured briefing of project state on demand. It auto-discovers what's in flight from git, GitHub, the project's `<instructions-file>` `## Project Map` section (when present), and whatever working-memory layout it can detect. The output reshapes based on what it finds — leads with active work if there is any, leads with what's next if everything is calm.

The audience is you, returning to a project after a session, a day, a week, or a vacation. You want to know where you are, what you were doing, and what to pick up — without re-reading every file. The skill is read-only on the project (it never modifies project files); the only exception is the briefing log it writes when you invoke it with `save`.

The skill is **convention-aware but not convention-coupled**. It works generically in any repo, but lights up with richer behaviour when the project follows the canonical conventions referenced below. When partial adoption is detected, the briefing's footer suggests what's missing — read-only suggestions, never edits.

## Canonical conventions reference

A single absolute URL, defined once and reused throughout the skill. If this is renamed or moved upstream, this is the single line to update.

```
<CANONICAL_CONVENTIONS_URL> = https://github.com/carlosboeing/agentic-toolkit/blob/main/guides/guide-project-structure-and-conventions.md
```

When the skill needs to point users at the conventions guide (e.g. in the convention-maturity footer block, or when explaining what `## Project Map` is), it renders this URL — optionally with a section anchor like `#58--project-map-section-in-claudemd` for §5.8 or `#65-ai-agent-update-triggers-working-memory-discipline` for §6.5.

## Synopsis

```
/briefing [depth] [save] [help]              # default — orientation briefing
/briefing sources [save] [help]              # self-documentation view (what this skill probes + finds)
/briefing setup [help]                       # add or update `## Project Map` in <instructions-file>

  depth     adaptive (default) | quick | standard | deep
            Length × source breadth. Adaptive is content-driven (sections appear
            based on project state). Explicit tiers force fixed-length output.
            Synonyms — quick: peek; deep: deep-dive
  sources   Render the self-documentation view: what this skill probes
            (Always-on / Declared / Default paths / Fallbacks) and what it
            found in the current project. Mutex with depth tiers and `setup`.
  setup     Add the `## Project Map` section to your `<instructions-file>`, or
            update it if it's already there. Future briefings then read
            your tracker, roadmap, changelog, and other locations from
            `<instructions-file>` directly instead of guessing.

            Setup mode reads what's already in your project, fills in
            each field where it can detect a value, marks the rest with
            `<placeholder>`, and shows you the proposed section. Nothing
            is written until you say yes. Before writing, it copies your
            `<instructions-file>` to `<instructions-file>.before-briefing-setup.bak` so you can
            restore the original.

            Can't be combined with depth tiers, `sources`, or `save`.
  save      Write the output to disk.                       default: off
            (synonyms: --save, export)
  help      Show this synopsis instead of running.          default: off
            (synonyms: ?, usage, --help, -h)

Examples:
  /briefing                    # adaptive default-mode briefing
  /briefing quick              # quick tier
  /briefing deep save          # deep tier, written to disk
  /briefing sources            # self-documentation view
  /briefing sources save       # self-documentation view, written to disk
  /briefing setup              # add or update `## Project Map` in <instructions-file>
```

Order of args does not matter. `/briefing deep save` and `/briefing save deep` are equivalent. If any help keyword (the full set is listed under **How to parse the args** below — `help`, `--help`, `-h`, `?`, `usage`) appears anywhere in the args, the skill renders this Synopsis as the response and stops — no briefing, no save.

The depth default is **adaptive**: when no depth keyword is provided, the briefing's length is content-driven — sections appear or disappear based on what the project state actually contains. `quick`, `standard`, and `deep` are explicit overrides for fixed-length tiers; "no dial" is its own behaviour, not a synonym for `standard`.

## Platform tool mappings

When executing the instructions in this skill (reading files, executing commands, creating files, asking user questions), use the appropriate tool for your active runtime:

| Action | Claude Code | Antigravity CLI (`agy`) | Cursor CLI | Codex | Kimi Code | Grok |
|---|---|---|---|---|---|---|
| **Read file** | `Read` | `view_file` | Native view / `cat` | `shell` (e.g. `cat`) | `Read` | `read_file` |
| **Write/Create file** | `Write` | `write_to_file` | Native edit | `apply_patch` / `shell` | `Write` | `write` |
| **Edit file** | `Edit` | `replace_file_content` | Native edit | `apply_patch` | `Edit` | `search_replace` |
| **Run command** | `Bash` | `run_command` | Native terminal | `shell` | `Bash` | `run_terminal_command` |
| **Search files** | `Grep` | `grep_search` | Native search | `shell` (e.g. `grep`) | `Grep` | `grep` |
| **Ask user** | `AskUserQuestion` | `ask_question` | Native input | `request_user_input` | `AskUserQuestion` | `ask_user_question` |
| **Dispatch subagent** | `Agent` | `invoke_subagent` | Native agent | `spawn_agent` | `Agent` | `spawn_subagent` |

## Instructions file resolution

To support multiple platforms and harnesses, the briefing skill abstracts the project instructions file (e.g., `CLAUDE.md` or `AGENTS.md`) as `<instructions-file>`. When reading or writing this file, resolve the path using these rules:

- **Active Runtime Defaults:**
  - On Claude Code, default to `CLAUDE.md`.
  - On agy, Cursor, Codex, Kimi, and Grok, default to `AGENTS.md`.
- **Existing Files Check:**
  - If only one file exists, use it.
  - If both exist, use the active runtime's default.
  - If neither exists, default to `CLAUDE.md` under Claude Code, and `AGENTS.md` under others.
- **Symlink / Pointer Resolution:**
  - If a project contains `AGENTS.md` pointing to `CLAUDE.md` (or vice-versa) or a symlink exists, resolve the target. To preserve the symlink itself and avoid overwriting it, all setup writes/edits must be written directly to the resolved target file (e.g., `CLAUDE.md`) rather than replacing the symlink path.
- **Backup File:**
  - The backup file is always `<instructions-file>.before-briefing-setup.bak`.

## How to parse the args

Walk the tokens once and bucket each one:

- **Mode keywords** (closed set): `sources`, `setup`. Default mode is briefing.
- **Depth keywords** (closed set): `quick`, `peek`, `standard`, `deep`, `deep-dive`. Default: adaptive (no override) if no depth keyword is present.
- **Save keywords** (closed set): `save`, `--save`, `export`. Default off.
- **Help keywords** (closed set): `help`, `--help`, `-h`, `?`, `usage`. If any appear, **short-circuit**: render the Synopsis above and stop.
- **Anything else**: respond with `unknown arg <X> — try /briefing help` and stop.

The parser is order-independent and case-insensitive. Two of the same bucket is an error of intent — pick the **rightmost** occurrence and surface the override via the depth-conflict bullet in the `★ About this briefing` block (see **About this briefing** section below). The bullet text follows the pattern `Depth received both '<X>' and '<Y>'; using '<Y>'`.

**Mutex rule — modes vs depth tiers:** when any mode keyword (`sources` or `setup`) is present AND a depth keyword is present, render the mode's view; the depth keyword is ignored. Surface the conflict via bullet 6 of `★ About this briefing` inside the mode's view: `Depth ignored when '<mode>' mode is active`.

**Mutex rule — modes are mutually exclusive:** when both `sources` and `setup` are present, that's an error of intent. Render `Cannot combine 'sources' and 'setup' modes — pick one.` and stop.

**Save compatibility:**
- `sources` + `save`: compatible (writes the sources view to `briefing-log/<TS>-sources.md`).
- `setup` + `save`: not compatible — setup mode's output is interactive (proposal + confirmation prompt), not a static document. Surface as bullet 6 of `★ About this briefing` inside the setup view: `Save ignored when 'setup' mode is active`. Proceed with setup.

## Source layering

From carlosboeing/agentic-toolkit, MIT.

More from carlosboeing/agentic-toolkit