Keep the personal half of the desktop in one place, and ask before installing it
Agent instructions, skills, SSH host aliases and expansion triggers are worth having identical on every machine one person owns, and belong in none of the shared configuration. They live in user/ now, with a manifest saying where each piece goes and a link-user stage that puts it there. That stage does nothing unless the machine said yes. Somebody who clones Panama to try the desktop keeps their own ~/.claude/CLAUDE.md exactly where it was; the question names the destinations and defaults to no. Anything displaced goes to config/old rather than being deleted. ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md were byte-identical copies of one file, which is the drift this exists to prevent. Also adds the vitals toggles for the battery and Claude usage readouts, which had preferences and no way to reach them.
This commit is contained in:
Gabriel Brown
@@ -0,0 +1,216 @@
|
||||
---
|
||||
name: create-ticket
|
||||
description: Use when Gib is authoring a Jira ticket himself and wants it written for him, e.g. /create-ticket KACP-XXXXX pointing at an empty or placeholder-titled story, spike, or task that needs its summary, description, and acceptance criteria filled in.
|
||||
---
|
||||
|
||||
# Create Ticket
|
||||
|
||||
Fills out a Jira ticket Gib is authoring: fetches the (usually empty) ticket, gathers
|
||||
context from the epic and local docs, writes the content in the Ksense house format,
|
||||
and updates the ticket in Jira. Invoked as `/create-ticket KACP-XXXXX`, with the key
|
||||
as the skill's arguments. Multiple keys may be passed to fill several tickets in one
|
||||
run, each processed fully before the next.
|
||||
|
||||
This is the authoring counterpart to the `/ticket` skill, which is for working
|
||||
tickets assigned to Gib. This skill only writes ticket content, it never creates
|
||||
branches, plans, or code.
|
||||
|
||||
The house formats below are extracted from the team's "Claude Project Manager"
|
||||
prompt, which the rest of the team uses through claude.ai. Keeping these formats
|
||||
identical is the point: a story written here must be indistinguishable in structure
|
||||
from one written by the PM team. The chat-oriented parts of that prompt (workflow
|
||||
classification tree, the Revise: loop, the questions-by-impact feedback table,
|
||||
meeting agendas, email templates) are deliberately not part of this skill.
|
||||
|
||||
## Jira access
|
||||
|
||||
Same conventions as the `/ticket` skill:
|
||||
|
||||
- Always Gib's credentials: run `source ~/.bashrc 2>/dev/null` in the same Bash call
|
||||
before any Jira command, then check `JIRA_CREDENTIALS` is set. Never use staging
|
||||
Infisical's Jira credentials. `JIRA_BASE_URL` defaults to
|
||||
`https://ksense-tech.atlassian.net`.
|
||||
- Fetch with `~/.agents/skills/ticket/scripts/jira-fetch-issue.sh <KEY> <OUT.json>`
|
||||
(rendered description, full field map) or plain curl against
|
||||
`/rest/api/3/issue/<KEY>`.
|
||||
- Write with curl: `PUT /rest/api/2/issue/<KEY>` with a JSON body like
|
||||
`{"fields": {"summary": "...", "description": "..."}}`. The v2 endpoint accepts
|
||||
Jira wiki markup in `description`, which is the reliable scriptable path for
|
||||
tables and headings. Expect HTTP 204 on success.
|
||||
|
||||
## Process
|
||||
|
||||
1. **Fetch context.** Get the ticket, its parent epic, and the sibling summaries
|
||||
(`parent = <EPIC> ORDER BY created`). Read the local epic folder if one exists,
|
||||
`.claude/docs/epics/<EPIC-KEY>/`, including any deliverables, plans, or epic
|
||||
breakdown documents there. Those documents are usually where the real scope for
|
||||
each story has already been worked out, so the ticket should say what they say,
|
||||
not a fresh invention. If the repo is relevant (a rebuild of an existing page,
|
||||
a schema change), check the actual code before describing current behavior.
|
||||
2. **Pick the artifact type.** Story is the default. Spike when the ticket is an
|
||||
investigation (title says Spike, or the goal is answering questions rather than
|
||||
shipping). Point task for a single trivial change. If genuinely ambiguous, ask
|
||||
Gib rather than guessing.
|
||||
3. **Resolve open questions before writing.** The team prompt appends a
|
||||
questions-by-impact table for chat iteration. Here, do it live instead: if
|
||||
something high-impact is genuinely undecided and not answerable from the docs,
|
||||
epic, or code, ask Gib directly (AskUserQuestion) before drafting. Low-impact
|
||||
unknowns become numbered Notes on the story, kept few.
|
||||
Where the open question is not Gib's to answer, because it belongs to the PM, a
|
||||
designer, or the client, do not put it to him as though it were. Say who owns it,
|
||||
and offer to draft a questionnaire with `/to-questionnaire` so it can go to that
|
||||
person in one pass. If Gib would rather ship the story without waiting, the question
|
||||
becomes a numbered Note naming its owner.
|
||||
4. **Draft the content** in the matching format below, in markdown first.
|
||||
5. **Overwrite guardrail.** If the ticket already has a non-trivial description
|
||||
(anything beyond a placeholder), show what is there and confirm before
|
||||
replacing it. Empty or placeholder tickets are filled without asking.
|
||||
6. **Write to Jira.** Convert the markdown to wiki markup (cheat sheet below) and
|
||||
PUT it. If the current summary is a placeholder or fake name, replace it with a
|
||||
real title, following whatever prefix convention the epic's siblings use (for
|
||||
example `UI - `, `Datamodel - `). Never touch tickets other than the ones asked
|
||||
for.
|
||||
7. **Verify.** Refetch with `expand=renderedFields` and check the description
|
||||
rendered as intended, especially tables. Fix and re-PUT if anything rendered as
|
||||
literal markup.
|
||||
8. **Keep a local copy.** Save the markdown version to
|
||||
`.claude/docs/epics/<EPIC-KEY>/<TICKET-KEY>/story.md` (or `spike.md` /
|
||||
`task.md`), creating directories as needed. These are personal docs, never
|
||||
committed.
|
||||
|
||||
## House rules for all content
|
||||
|
||||
- Spelling: always `Ksense` (not KSENSE or KSense), always `Knack` (transcripts
|
||||
often mis-transcribe it as NAC).
|
||||
- Plain punctuation. No em dashes, en dashes, semicolons, or arrow glyphs.
|
||||
- Acceptance criteria are user-focused, independent, and testable, phrased in third
|
||||
person present tense with the user as subject.
|
||||
- Priorities are P1, P2, P3.
|
||||
- Notes are numbered and referenced from the AC table's Referenced Note column by
|
||||
number. Drop any note that just restates an AC.
|
||||
- If requirements came from a video or call recording, the Artifacts field is
|
||||
`See Video` and a note says `Requirements extracted from provided video
|
||||
walkthrough`. Never paste transcript text into the ticket.
|
||||
- Do not invent scope. Everything in the ticket must trace to the epic docs, the
|
||||
deliverables, the code, or what Gib said. Thin ticket beats padded ticket.
|
||||
|
||||
## Story format
|
||||
|
||||
```
|
||||
## **As a [type of user], I want to [perform some action] so that I can [achieve some goal or benefit].**
|
||||
|
||||
**Acceptance Criteria:**
|
||||
| ID | Acceptance Criteria | Referenced Note | Priority | Completed |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| AC-1 | [Requirement] | [Note number or blank] | P1 | |
|
||||
| AC-2 | [Requirement] | | P2 | |
|
||||
|
||||
**Notes:**
|
||||
1. [Detailed note]
|
||||
2. [Detailed note]
|
||||
|
||||
**Technical Requirements:**
|
||||
- **Work Type**: [Standard Knack/Knack + Custom Code/Full Custom]
|
||||
- **Custom Code Components**: [None/JavaScript/CSS/External API/...]
|
||||
- **Code Robustness**: [MVP/Standard/High]
|
||||
- **Test Coverage**: [None/Basic/Comprehensive]
|
||||
- **Security Level**: [Basic/Enhanced/Compliance-Required]
|
||||
|
||||
**Testing Requirements:**
|
||||
- [Browser compatibility, mobile responsive, error handling, role testing, as applicable]
|
||||
|
||||
**Artifacts**
|
||||
[See Video | links | None]
|
||||
```
|
||||
|
||||
The Jira summary is the story title, so the description starts at the As-a
|
||||
sentence. Command Center work is always `Full Custom` (Next.js/React); the Knack
|
||||
work types and the `Knack Implementation Details` block (Objects Affected,
|
||||
Views/Pages, Code Placement) exist only for Knack app tickets, include that block
|
||||
only then. Technical Requirements and Testing Requirements are included for any
|
||||
ticket involving custom code, which for KCC is all of them except pure-copy
|
||||
changes.
|
||||
|
||||
Level definitions, used verbatim when choosing values:
|
||||
|
||||
- Code Robustness: MVP is happy path only, proof of concept. Standard handles
|
||||
common edge cases with user-friendly errors, production-ready. High handles all
|
||||
edge cases with detailed logging and graceful degradation.
|
||||
- Test Coverage: None is manual developer testing. Basic covers critical paths
|
||||
with unit tests. Comprehensive is full unit plus integration coverage.
|
||||
- Security Level: Basic is platform-standard. Enhanced adds role-based
|
||||
permissions, audit logging, or data protection concerns. Compliance-Required
|
||||
means HIPAA/PCI/government standards.
|
||||
|
||||
## Spike format
|
||||
|
||||
```
|
||||
**Investigation Goal:**
|
||||
[What question(s) need to be answered? What decision needs to be made?]
|
||||
|
||||
**Context:**
|
||||
[Why is this investigation needed? What problem are we trying to solve?]
|
||||
|
||||
**Questions to Answer:**
|
||||
| Priority | Question | Why It Matters |
|
||||
| --- | --- | --- |
|
||||
| High | [Question] | [Impact on architecture/design/timeline] |
|
||||
| Medium | [Question] | [Impact] |
|
||||
|
||||
**Investigation Tasks:**
|
||||
* [ ] Research [specific topic]
|
||||
* [ ] Prototype [specific approach]
|
||||
* [ ] Document findings
|
||||
|
||||
**Success Criteria:**
|
||||
- All high-priority questions answered with data or evidence
|
||||
- Clear recommendation documented for team decision
|
||||
- Findings shared in [format]
|
||||
|
||||
**Time Box:** [X hours/days]
|
||||
|
||||
**Deliverables:**
|
||||
- Written findings document
|
||||
- Code prototype (if applicable)
|
||||
- Recommendation with pros and cons
|
||||
|
||||
**Notes:**
|
||||
[Constraints, risks, additional context]
|
||||
```
|
||||
|
||||
Spikes measure success by answered questions and a recommendation, not shipped
|
||||
functionality. Keep the questions table to what actually blocks or informs the
|
||||
implementation decision.
|
||||
|
||||
## Point task format
|
||||
|
||||
```
|
||||
**Location**: [Object/View/Form/route identifier]
|
||||
**Action**: [Specific change required]
|
||||
**Success Criteria**: [How to verify completion]
|
||||
**Notes**: [Only if essential]
|
||||
```
|
||||
|
||||
For a single trivial change. No story sentence, no AC table.
|
||||
|
||||
## Markdown to Jira wiki markup cheat sheet
|
||||
|
||||
For the v2 `description` field:
|
||||
|
||||
- `## Heading` becomes `h2. Heading` (h3. for deeper)
|
||||
- `**bold**` becomes `*bold*`
|
||||
- Table header row `| A | B |` becomes `||A||B||`, body rows stay `|A|B|`, one row
|
||||
per line, no separator row
|
||||
- Numbered list items become `# item`, bullets become `* item`
|
||||
- Checkboxes have no wiki syntax, so Investigation Tasks render as plain bullets
|
||||
and the Completed column stays blank (the team fills it in Jira)
|
||||
- Code spans stay `{{monospace}}`, blocks become `{code}...{code}`
|
||||
- Literal square brackets in prose must be avoided, wiki markup reads `[...]` as a
|
||||
link
|
||||
- Checked boxes in team templates: `[ ]` renders literally and is fine to keep for
|
||||
unchecked options, but `[x]` renders as a red error span. Mark selected options
|
||||
with `(/)`, Jira's green check icon, instead
|
||||
|
||||
Send the description as one string with `\n` newlines. After the PUT, always do
|
||||
the rendered-fields verification pass, wiki table syntax fails quietly when a row
|
||||
has mismatched pipes.
|
||||
Reference in New Issue
Block a user