feat: refresh shared skills catalog
This commit is contained in:
vasily committed
1 parent
98bb35e6fb
commit
418792d1ec
49 files changed
+2273
-2390
No files matched your search
@@ -1,77 +1,29 @@
|
||||
---
|
||||
name: git-workflow
|
||||
description: >
|
||||
Atomic commit grouping, selective staging, conventional commit messages, and clean git history hygiene.
|
||||
Use when preparing commits, staging changes selectively, reviewing git diffs, or standardizing commit messages.
|
||||
concerns: [system-one-balance]
|
||||
Inspect, stage, commit, and manage isolated branches and pull requests. Enforces worktree isolation and structured PR telemetry.
|
||||
scope: global
|
||||
---
|
||||
|
||||
# Git Workflow & Atomic Staging
|
||||
# Git workflow
|
||||
|
||||
Enforces clean, logical version control hygiene, atomic commits, and conventional commit standards across repositories.
|
||||
1. **Isolation**: When starting complex or multi-step tasks, operate within an
|
||||
isolated physical worktree ([references/worktrees.md](references/worktrees.md))
|
||||
or a T3 Code managed thread workspace. Never commit directly to primary branches
|
||||
(`main` or `master`).
|
||||
2. **Inspection**: Inspect staged, unstaged, and untracked changes. Identify
|
||||
ownership and requested scope before staging anything.
|
||||
3. **Cohesive grouping**: Group commits by complete behavior. Keep implementation,
|
||||
tests, and docs together when they belong to the same change; do not split
|
||||
automatically by file type or layer.
|
||||
4. **Staging & checks**: Stage named files or selected hunks. Preserve unrelated user
|
||||
edits. Run relevant checks under [shared verification](../../protocols/workflow.md#verification)
|
||||
and formatters. Use conventional commit messages (`feat:`, `fix:`, `perf:`, `docs:`).
|
||||
5. **Pull requests & telemetry**: Push feature branches and generate pull requests
|
||||
using `gh pr create` with the structured WHAT-WHY-HOW-LEARNINGS format
|
||||
([references/pr-template.md](references/pr-template.md)).
|
||||
6. **Cleanup**: Remove ephemeral worktrees after PR creation or merge.
|
||||
|
||||
---
|
||||
|
||||
## Phase 0: Setup and Protocols
|
||||
|
||||
1. **Non-Negotiable Invariants**:
|
||||
- **Never Stage Unrelated Edits**: Inspect `git status` and diffs before staging. Stage only files directly relevant to the current task. Preserve untouched user work.
|
||||
- **Never Use Destructive Resets**: Never execute `git reset --hard` or `git checkout .` without explicit user instruction.
|
||||
- **Verify Before Committing**: Run quality gates (tests, linter) before creating commits.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Ingest and Check
|
||||
|
||||
1. Run `git status` to inspect modified, staged, and untracked files.
|
||||
2. Review `git diff` for staged vs. unstaged changes to ensure no extraneous edits or debug logs are included.
|
||||
3. Identify the logical boundaries of the work to separate independent changes.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Processing (Core Logic)
|
||||
|
||||
### Step 1: Logical Commit Grouping
|
||||
Group changes into focused, cohesive commits rather than bulk-committing unrelated subsystems:
|
||||
1. **Infrastructure & DDL**: Table migrations, config schemas, and models.
|
||||
2. **Core Logic**: Services, domain algorithms, and processors.
|
||||
3. **API & Routes**: Web endpoints, controllers, and schemas.
|
||||
4. **Tests & Docs**: Automated tests, documentation, and specs.
|
||||
|
||||
### Step 2: Selective Staging
|
||||
- Stage specific files explicitly:
|
||||
```bash
|
||||
git add path/to/file1 path/to/file2
|
||||
```
|
||||
- Avoid blanket `git add .` when unstaged experimental edits exist in the workspace.
|
||||
|
||||
### Step 3: Conventional Commit Formatting
|
||||
Follow standard conventional commit prefixes:
|
||||
- `feat(<scope>):` New functionality or feature.
|
||||
- `fix(<scope>):` Bug fix or regression resolution.
|
||||
- `refactor(<scope>):` Code restructuring without behavioral change.
|
||||
- `perf(<scope>):` Performance optimization.
|
||||
- `sec(<scope>):` Security hardening or vulnerability fix.
|
||||
- `docs(<scope>):` Documentation updates.
|
||||
- `test(<scope>):` Adding or updating tests.
|
||||
- `chore(<scope>):` Tooling, dependencies, or maintenance.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: The System One Balance Pass
|
||||
|
||||
- **Augment, Don't Handcuff**:
|
||||
- Safe operations (e.g. `git status`, `git diff`, staging known files, creating a commit) must be frictionless fast paths.
|
||||
- Do NOT prompt the user with interactive confirmation modals for routine commits during an ongoing implementation.
|
||||
- Reserve confirmation prompts strictly for irreversible actions (`git push --force`, `git branch -D`, `git clean -fdx`).
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Output Execution & Verification
|
||||
|
||||
1. Create the commit with a concise, descriptive message.
|
||||
2. Verify commit creation:
|
||||
```bash
|
||||
git log -n 1 --oneline
|
||||
```
|
||||
3. Confirm working tree status remains clean and expected.
|
||||
No routine confirmation prompt is needed for authorized staging or commits on
|
||||
feature branches. Destructive operations (force push, hard reset) are strictly
|
||||
forbidden under repository negative constraints.
|
||||
@@ -0,0 +1,35 @@
|
||||
# Standard Pull Request Telemetry Template
|
||||
|
||||
Use this markdown structure for automated pull request bodies (`gh pr create --body-file ...`)
|
||||
and formal task completion records:
|
||||
|
||||
```markdown
|
||||
## 1. WHAT (System Modifications)
|
||||
- **Modified Components**:
|
||||
- `path/to/modified_file.ext`
|
||||
- **Added Assets**:
|
||||
- `path/to/new_file.ext`
|
||||
- **Removed Assets**:
|
||||
- None
|
||||
|
||||
## 2. WHY (Context & Architectural Intent)
|
||||
- **Problem Statement**: Concise description of defect, bottleneck, or requirement.
|
||||
- **Requirement Traceability**: Issue # / Task ID / Plan bead.
|
||||
- **Design Justification**: Rationale for chosen implementation architecture.
|
||||
|
||||
## 3. HOW (Technical Implementation & Verification Evidence)
|
||||
- **Implementation Details**: Summary of algorithmic, API, or structural updates.
|
||||
- **Deterministic Verification Evidence**:
|
||||
- **Command**: `pytest tests/unit/test_target.py -v`
|
||||
- **Exit Code**: `0`
|
||||
- **Output Metrics**: `XX passed, 0 failed, 100% pass rate`
|
||||
- **Static Analysis & Linting**:
|
||||
- **Command**: `ruff check src/`
|
||||
- **Result**: Clean (0 errors)
|
||||
|
||||
## 4. LEARNINGS & ARCHITECTURAL GOTCHAS
|
||||
- **Operational Traps**: Specific runtime, environment, or dependency quirks discovered.
|
||||
- **Uncovered Debt**: Latent issues, missing coverage, or obsolete patterns identified.
|
||||
- **Indexed Gotchas**: Reference to saved `docs/gotchas/<slug>.md` if applicable.
|
||||
- **Follow-up Recommendations**: Subsequent tasks or architectural considerations.
|
||||
```
|
||||
@@ -0,0 +1,60 @@
|
||||
# Physical Git Worktree Isolation
|
||||
|
||||
Developing directly on primary branches (`main` or `master`) or in a single shared
|
||||
working directory creates severe multi-agent concurrency risks:
|
||||
- Uncommitted edits from concurrent tasks get overwritten or cross-contaminated.
|
||||
- Branch switches abort background compilations or active test suites.
|
||||
- Half-finished experiments accidentally leak into tracking branches.
|
||||
|
||||
Physical Git worktrees resolve concurrency at the filesystem level. Each task or
|
||||
agent operates in an independent physical directory linked to the shared `.git`
|
||||
repository.
|
||||
|
||||
## Standard worktree lifecycle
|
||||
|
||||
### 1. Provision a dedicated worktree
|
||||
From the repository root:
|
||||
|
||||
```sh
|
||||
# Create a new feature branch in an isolated worktree directory
|
||||
git worktree add -b feat/<task-id> ../worktrees/<task-id> main
|
||||
cd ../worktrees/<task-id>
|
||||
```
|
||||
|
||||
### 2. Implement, verify, and commit
|
||||
Inside the isolated worktree:
|
||||
- Make targeted changes.
|
||||
- Run local tests and deterministic formatters.
|
||||
- Stage changes and commit using conventional commit format:
|
||||
```sh
|
||||
git add <files>
|
||||
git commit -m "feat(module): implement scoped capability"
|
||||
```
|
||||
|
||||
### 3. Push and generate pull request
|
||||
Push the branch to remote origin:
|
||||
```sh
|
||||
git push -u origin feat/<task-id>
|
||||
```
|
||||
|
||||
Create the pull request via GitHub CLI using the WHAT-WHY-HOW-LEARNINGS template:
|
||||
```sh
|
||||
gh pr create \
|
||||
--title "feat(module): implement scoped capability" \
|
||||
--body-file docs/reports/<task-id>-telemetry.md \
|
||||
--base main \
|
||||
--head feat/<task-id>
|
||||
```
|
||||
|
||||
### 4. Cleanup after merge
|
||||
Once the PR is merged or the task is completed:
|
||||
```sh
|
||||
cd ../main-repo
|
||||
git worktree remove ../worktrees/<task-id>
|
||||
```
|
||||
|
||||
## T3 Code managed worktrees
|
||||
When operating within the T3 Code control plane, worktree provisioning, branch
|
||||
isolation, and diff tracking are handled natively per conversation thread. Use
|
||||
T3 Code's built-in PR tools (`link_pull_request`, `list_thread_pull_requests`) to
|
||||
associate PRs with the active task.
|
||||
Reference in new issue
Block a user