main

Global Agent Instructions

Canonical global instructions shared across all AI coding agents (pi, Claude, Codex, Copilot, Gemini, opencode, …). Symlinked into each agent’s expected instruction file by dots/Makefile.

Core Principles

  1. Command Line First, Code First: Build deterministic CLI tools before AI wrappers
  2. Progressive Disclosure: Load context in tiers (essential, contextual, reference)
  3. Structured Communication: Get to the point, use scannable formatting
  4. Honesty and Uncertainty: Say “I don’t know” when uncertain

Think Before Coding

Don’t assume. Don’t hide confusion. Surface tradeoffs.

  • State assumptions explicitly. If uncertain, ask.
  • If multiple interpretations exist, present them — don’t pick silently.
  • If a simpler approach exists, say so. Push back when warranted.
  • If something is unclear, stop. Name what’s confusing. Ask.

Write the Laziest Code That Works

Lazy means efficient, not careless. The best code is the code never written. Understand the problem and trace the real flow first, then stop at the first rung that holds:

  1. Does this need to exist at all? Speculative need → skip it, say so. (YAGNI)
  2. Already in this codebase? Reuse the helper/util/type/pattern. Look before you write.
  3. Stdlib does it? Use it.
  4. Native platform feature covers it? (<input type="date"> over a picker lib, CSS over JS, DB constraint over app code.)
  5. Already-installed dependency solves it? Use it. Never add a new dep for what a few lines do.
  6. Can it be one line? One line.
  7. Only then: the minimum code that works.
  • Bug fix = root cause, not symptom. Grep every caller; fix once where they route through.
  • No unrequested abstractions, no speculative scaffolding; deletion over addition, boring over clever, fewest files.
  • Never simplify away: trust-boundary validation, error handling that prevents data loss, security, accessibility, or anything explicitly requested. If the user insists on the full version, build it — no re-arguing.
  • Never be lazy about understanding; the ladder shortens the solution, never the reading.
  • Mark deliberate shortcuts with a ponytail: comment naming the ceiling and upgrade path: # ponytail: global lock, per-account locks if throughput matters.

Surgical Changes

Touch only what you must. Clean up only your own mess.

When editing existing code:

  • Don’t “improve” adjacent code, comments, or formatting.
  • Don’t refactor things that aren’t broken.
  • Match existing style, even if you’d do it differently.
  • If you notice unrelated issues, mention them — don’t fix them.

When your changes create orphans:

  • Remove imports/variables/functions that YOUR changes made unused.
  • Don’t remove pre-existing dead code unless asked.

The test: every changed line should trace directly to the user’s request.

Git Safety

  • ALWAYS use explicit refspecs for git push: git push origin branch:branch
  • NEVER use bare git push - branch tracking can push to unexpected branches
  • Before pushing, verify the tracking branch with git status

Stack Preferences

  • Package managers: uv for Python (NOT pip)
  • Markdown over HTML/XML: Use markdown for responses and docs; HTML is fine for visual deliverables when explicitly requested
  • Analysis vs Action: If asked to analyze, do analysis only
  • Org files: NEVER edit .org files directly — use emacsclient or org_todo tool

When users refer to past work, choose the appropriate tool:

  • Saved sessions (past tense: “yesterday’s session”, “last week’s work”): Use list_saved_sessions and read_saved_session tools to search curated markdown summaries in ~/.local/share/ai/sessions/. These are structured, human-readable summaries with context and learnings.

  • Current/active threads (present tense: “this conversation”, “what did I just say”): Use find_threads and search_thread tools to search raw JSONL conversation data in ~/.pi/agent/sessions/. Useful for debugging or finding exact conversation details.

Default to list_saved_sessions for historical lookups unless specifically asked for raw conversation data.

Response Patterns

  1. Understand: Clarify the task and requirements
  2. Plan: Break down complex tasks into verifiable steps
  3. Execute: Implement systematically
  4. Verify: Test and validate results
  5. Document: Capture decisions and outcomes

For multi-step tasks, state a brief plan with verification:

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

Strong success criteria let you loop independently. Weak criteria (“make it work”) require clarification first.

name: tailwind description: > Red Hat TAILWIND — Product Management skills, PMM and TMM skills, Domain 0 installer and program skills, and the Knowledge Registry (schema + registry/). BU-specific keys and tokens live only in local config; never commit secrets.

TAILWIND

This repository is the program home for TAILWIND: skills, agents, commands, installer, registry, and documentation for PM, PMM, TMM, and Domain 0.

Layout

Path Contents
skills/ All Agent Skills (<skill-id>/SKILL.md). PM, PMM, TMM, Domain 0, registry intake, and shared utilities.
agents/ Agent definitions (*.md) for PM and TMM workflows.
commands/ Slash-command specs (primarily PM); extend for other domains as needed.
examples/ Worked examples and sample outputs.
context/ Shared context files (e.g. optional knowledge-registry-index.yaml snapshot).
registry/ + schema/ + index.yaml Knowledge Registry source rows and generated index.
scripts/ PM and shared automation. scripts/registry/ — validate, generate index, audit.
installer/ Tailwind CLI bootstrap and tailwind command (Domain 0).
docs/product-management/ PM lifecycle, onboarding, commands, workstream categories (README).
docs/domain0/ Installer deep dives copied from Domain 0.
docs/product-marketing/ PMM references (including gem-conversion-testing assets).
docs/technical-marketing/ TMM (Domain 2) orientation: overview and index.
docs/registry/ Knowledge Registry contributor and agent consumption guides.
.claude-plugin/plugin.json Claude Code plugin manifest (tailwind id → /tailwind: slash-command namespace).
.claude-plugin/marketplace.json In-repo marketplace catalog; plugin source is this repo root (./).

Conventions

  • Human in the loop: Treat outputs as drafts until validated against sources of record (Jira, GitLab, approved program docs). See docs/responsible-use.md.
  • Lola: installer/lib/tailwind/core/lola.sh registers a single module named tailwind from repo ${TAILWIND_GIT_ORG}/${TAILWIND_GIT_REPO} (default tailwind/tailwind). Override with TAILWIND_GIT_REPO if your GitLab slug differs.
  • Bootstrap: installer/bootstrap.sh clones this repository (default ~/Projects/tailwind).
  • MCP: Configure per mcp/README.md and mcp/mcp.json.example.
  • Sources of truth for program intent: approved program docs in the TAILWIND program folder (Google Drive) and maintainer channels; authoritative link metadata lives in this repo under registry/ and index.yaml.
  • Contributions: CONTRIBUTING.md; maintainers: MAINTAINERS.md.

Cursor

Load .cursor/rules/ as project rules. For skills, open skills/<skill-id>/SKILL.md paths and @-mention in chat.

Claude Code

This repository is both the plugin (tailwind in plugin.json) and the marketplace catalog (tailwind in marketplace.json): .claude-plugin/plugin.json + .claude-plugin/marketplace.json. No separate marketplace repository—users add this Git URL as a marketplace and install the plugin from it.

Local dev (no install): from the repo root:

claude --plugin-dir .

Slash commands use the plugin namespace /tailwind: for Markdown files in commands/. Skills live under skills/. See docs/runtimes.md — Claude Code.

Install via marketplace (recommended for sharing): with Claude Code installed, use your clone URL (HTTPS or SSH):

/plugin marketplace add https://gitlab.cee.redhat.com/tailwind/tailwind.git

/plugin install tailwind@tailwind

Refresh catalog after upgrades: /plugin marketplace update. Private GitLab needs working git credentials (see plugin marketplaces — private repos).

Staying current (VPN and private GitLab)

Claude Code does not run a special sync when your VPN connects. Updates depend on Git reaching GitLab and when Claude Code refreshes (for example on startup or when you run /plugin marketplace update).

Practical pattern for most users

  1. Connect to VPN (or any network path) so git can reach this GitLab project without interactive prompts.
  2. Configure non-interactive access to private GitLab: use a credential helper or set GITLAB_TOKEN / GL_TOKEN in your environment (see Anthropic’s private repositories table). Without this, background updates may fail silently when you are off-VPN or when no terminal is available to prompt for credentials.
  3. After VPN is up, either restart Claude Code or run /plugin marketplace update so the marketplace catalog and installed plugin can pick up new commits from the default branch.

If you still see stale skills, run /plugin marketplace update again after your team publishes changes, or ask IT whether your VPN client supports a post-connect script that updates the local marketplace clone (an org-specific option outside Claude Code).

Treat examples/ and docs/ as file-backed context—@-reference or open in the IDE.

Maintainer

MAINTAINERS.md. Program coherence: Products AI CoE (per Charter / Reference).