diff --git a/AGENTS.md b/AGENTS.md index 27e625b..a0f7527 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -69,11 +69,27 @@ The `.agents/skills/` directory contains repo-specific skill files. Key skills: Use `skill` tool to load one when the task matches. +## Agent skills + +### Issue tracker + +Track issues in this repository's Gitea Issues using `tea`. See +`docs/agents/issue-tracker.md`. + +### Triage labels + +Use the five canonical triage labels without overrides. See +`docs/agents/triage-labels.md`. + +### Domain docs + +Use the single-context domain documentation layout. See `docs/agents/domain.md`. + ## Verify commands Run in order after source changes: -``` +```bash npm run check # svelte-kit sync + svelte-check (typecheck) npm run build # secretless Vite production build ``` diff --git a/CONTEXT.md b/CONTEXT.md new file mode 100644 index 0000000..d931be3 --- /dev/null +++ b/CONTEXT.md @@ -0,0 +1,271 @@ +# SHD.build Domain + +SHD.build is an independent community intelligence platform for _The Division +Resurgence_. This glossary defines the language used for player planning, shared +content, Game Data, governance, equipment, progression, and modeled mechanics. + +## Product and people + +**SHD.build**: The community platform described by this glossary. Always +capitalize `SHD` and write the product name as `SHD.build`. _Avoid_: SHD Build, +SHD Builder + +**Agent**: Any person using SHD.build, whether anonymous or authenticated. +_Avoid_: User, visitor, player when referring to product access + +**Anonymous Agent**: An Agent who is not signed in to SHD.build. _Avoid_: +Visitor, guest + +**Registered Agent**: An Agent with an SHD.build account. _Avoid_: Registered +user, member + +**Modeling Session**: An interactive agentic work session that prepares one +Mechanic Program at a time for a Registered Agent to confirm in chat before the +session submits it through an existing ISAC action. _Avoid_: Agent, Modeling +Client, bulk job + +**Contributor**: A Registered Agent who has accepted the contributor guidelines +and may submit proposed Game Data changes for review. _Avoid_: Editor when the +Agent cannot change Canonical Game Data directly + +**Operator**: A Registered Agent performing an authorized task in ISAC. +Contributor, reviewer, moderator, and administrator authority remain distinct +from this situational term. _Avoid_: Admin as a generic name for anyone using +ISAC + +**Oversight**: The human review function for proposed Game Data, moderated +Community Content, and identity assets. Use the qualified names Data Oversight, +Community Oversight, Guide Oversight, and Avatar Oversight when the review area +matters. _Avoid_: Moderation as a name for every review function + +## Planning and shared content + +**Builder**: The planning tool an Agent uses to configure a Loadout and inspect +supported calculations. _Avoid_: Build when referring to the tool + +**Loadout**: A complete planned character configuration, including selected +Equipment, progression choices, and combat assumptions. A Loadout may exist +without becoming a saved Build. _Avoid_: Build when persistence, ownership, or +sharing matters + +**Loadout Draft**: An editable Loadout that has not become a saved Build. +Anonymous and Registered Agents may both work with drafts. _Avoid_: Build draft + +**Build**: A saved, owned, and shareable planning artifact whose central content +is a Loadout. A Build may be Private, Unlisted, or Public and may derive from +another Build. _Avoid_: Loadout when persistence, ownership, or sharing matters + +**Guide**: A revisioned long-form community article that may include snapshots +of one or more Builds. A Guide is prose-led content rather than a Loadout +container. _Avoid_: Build guide when referring to every Guide + +**News Article**: A revisioned editorial or syndicated article published through +the News channel. _Avoid_: Guide, post + +**Article Revision**: An immutable edition of a Guide or News Article. Editors +select one revision for publication while later revisions may await review. +_Avoid_: Version when referring to published article history + +**Community Content**: Agent-authored comments, profile biographies, custom +avatars, and Guides governed by the shared moderation lifecycle. _Avoid_: +User-generated content, UGC + +**Community Note**: A visible comment that Community Oversight pins to a Public +Database discussion. It remains Community Content and follows the same removal +rules as other comments. _Avoid_: Official correction, staff note + +**Content Report**: An Agent's request for Oversight to review visible Community +Content, with no immediate change to the content's visibility. _Avoid_: Takedown +request + +**Public Database**: The Agent-facing reference view of Canonical Game Data. +_Avoid_: Database when the term could mean application storage + +## Game Data and governance + +**Game Data**: Community-maintained structured facts about _The Division +Resurgence_ used by the Public Database, Builder, Builds, and contribution +workflow. _Avoid_: Source data, builder data, reference data + +**Canonical Game Data**: The authoritative, approved body of Game Data. _Avoid_: +Live data, production data + +**Canonical Record**: One authoritative record within Canonical Game Data. +_Avoid_: Approved proposal + +**Contribution Proposal**: A pending request from a Contributor to create or +change Canonical Game Data. Approval still requires the proposed change to +satisfy the canonical rules for its record family. _Avoid_: Draft record, +pending record + +**ISAC**: The operational console for Game Data, contribution review, community +governance, identity and access management, audit history, and system +operations. _Avoid_: Admin panel, calculation engine + +**Registry**: An ISAC workspace containing one family of related records and its +management controls. _Avoid_: Table, list page + +**Audit Event**: An immutable account of a consequential operation or review +decision, including the actor, target, and change evidence. _Avoid_: Audit-log +row, activity log + +**Compensating Reversion**: A new operation that restores an earlier state while +preserving the original Audit Event and recording the reversal. _Avoid_: +Rollback, undo when either implies rewriting history + +## Equipment and progression + +**Equipment**: The items and enhancements selected for a Loadout, including +Weapons, Gear, Weapon Mods, Gear Mods, Skill Chips, and an OS Protocol. _Avoid_: +Item when the equipment relationship matters + +**Gear**: Equippable protective equipment assigned to a character slot. Gear may +provide core values, Attributes, a Brand Set, a Talent, and augmentation +capacity. _Avoid_: Armor as a collective name for all Gear + +**Body Armor**: The canonical name for the equippable torso Gear slot. _Avoid_: +Vest + +**Weapon**: An equippable firearm with a Weapon Category, damage and handling +properties, progression values, and applicable Talents and Mods. _Avoid_: Gun +when referring to the modeled record + +**Weapon Category**: The classification that groups Weapons as Shotgun, Rifle, +MMR, AR, LMG, or SMG. _Avoid_: Weapon type, weapon family + +**Weapon Mod**: An enhancement fitted to a compatible Weapon slot. Regular and +Exotic Weapon Mods follow different selection rules. _Avoid_: Attachment + +**Gear Mod**: An enhancement fitted to Gear according to the Gear's available +mod capacity. _Avoid_: Tactical Augment + +**Tactical Augment**: A numbered augmentation position recorded on selected Gear +in a Loadout. _Avoid_: Gear Mod + +**Attribute**: A named measurable game property with defined units and +calculation meaning. _Avoid_: Stat when referring to the canonical Attribute +catalog + +**Core Attribute**: One of the three primary character alignments: Firepower, +Toughness, or Engineering. _Avoid_: Main stat, primary stat + +**Brand Set**: A Gear identity whose bonuses depend on how many pieces from that +set the Loadout equips. _Avoid_: Gear set + +**Quality**: The item classification Standard, Specialized, Superior, or +High-end. Quality governs available or scaled properties for applicable +Equipment. _Avoid_: Rarity + +**Exotic**: A special scope used by certain Weapons, Talents, and Weapon Mods. +Exotic is not a fifth Quality. _Avoid_: Exotic quality + +**Item Level**: An Equipment progression coordinate used to resolve +level-dependent values. _Avoid_: Tier, Quality + +**Equipment Tier**: The T0, T1, or T2 progression band that controls Equipment +capabilities and values. _Avoid_: Talent Tier, Item Level + +**Talent Tier**: The Tier I or Tier II value variant of a Talent. _Avoid_: +Equipment Tier, T1, T2 when the distinction could be unclear + +**Reference Level**: The Item Level at which an observed value or range applies. +_Avoid_: Base level + +**Hidden Base**: A level-independent value inferred from observed Equipment +values and the game's progression rules. _Avoid_: Displayed Value, Raw Value + +**Raw Value**: A calculated value before the presentation rules that reproduce +the game's displayed number. _Avoid_: Hidden Base, Displayed Value + +**Displayed Value**: The player-visible number produced after applying the +game's presentation rules to a Raw Value. _Avoid_: Raw Value + +**OS Protocol**: A single equipped progression item with a Quality, Core +Attribute alignment, primary effect, inherited secondary profile, and +upgradeable Talent. _Avoid_: Protocol when the operating-system meaning could be +inferred + +**Skill**: A selectable combat capability associated with a Specialization. +Skills may own Skill Chip Sets and may have explicit compatibility relationships +with another Skill. _Avoid_: Ability or Specialization Ability for the +selectable game concept + +**Signature Skill**: A Specialization's defining Skill, distinguished from its +other selectable Skills. _Avoid_: Signature ability + +**Skill Chip**: An Equipment selection that modifies the Skill occupying its +Loadout position. Skill Chips belong to a Skill Chip Set and may provide +primary, secondary, and set effects. _Avoid_: Chip when the equipment family is +unclear + +**Skill Chip Set**: A reusable Skill Chip definition associated with a Skill, +including its set bonus and optional Talent. An explicit compatibility +relationship may let another Skill equip the set. _Avoid_: Skill set + +**Specialization**: A character progression identity containing Focuses, Skills, +and progression choices. _Avoid_: Class + +**Focus**: A path within a Specialization aligned to one Core Attribute and +defining a selection of Skills and progression choices. _Avoid_: Subclass, +specialization path + +**Talent**: A named conditional behavior owned by its source, such as a Weapon, +Gear item, OS Protocol, or Skill Chip Set. Different Talent sources may use +different progression variants. _Avoid_: Perk, passive + +## Modeled mechanics + +**Mechanic Program**: The structured, source-owned description of a Talent or +other conditional behavior. It captures the conditions, state changes, and +outcomes needed to evaluate that behavior. _Avoid_: Script, Trigger record + +**Event**: An observed occurrence on a combat timeline that a Mechanic Program +may inspect. _Avoid_: Trigger when referring to the occurrence itself + +**Trigger Condition**: The criteria that an Event must satisfy before a mechanic +can proceed toward Activation. A Trigger Condition is part of a Mechanic +Program, not a standalone Game Data record. _Avoid_: Trigger as an entity + +**Activation**: A successful mechanic occurrence after its Event, conditions, +chance, and Cooldown requirements resolve. _Avoid_: Proc when precision matters + +**Cooldown**: The period after a successful Activation during which the same +mechanic cannot activate again. A failed chance does not begin the Cooldown. +_Avoid_: Delay + +**Mechanic State**: A value retained across Events for one mechanic, such as a +flag, count, stack, duration, mark, or resource. _Avoid_: Runtime state when +discussing game behavior + +**Outcome**: The effect emitted by an activated mechanic, such as an Attribute +change, damage, restoration, resource change, or marker. _Avoid_: Effect when +the source Talent and emitted result could be confused + +**Combat Profile**: The encounter assumptions and observed rates used to project +a Loadout's combat performance. _Avoid_: Simulation when no event simulation +occurs + +**Scenario Input**: An explicit encounter assumption required to evaluate a +mechanic whose result cannot be determined from the Loadout alone. _Avoid_: +Guess, default assumption + +**Ready**: The mechanic readiness state indicating that typed Game Data can +evaluate the mechanic without additional Scenario Inputs. _Avoid_: Complete + +**Requires Assumptions**: The mechanic readiness state indicating that +evaluation needs one or more explicit Scenario Inputs. _Avoid_: Ready, +unsupported + +**Captured Only**: The mechanic readiness state indicating that SHD.build +preserves the authored behavior but cannot calculate it. _Avoid_: Unsupported +when the behavior has still been recorded + +**Extra Health**: Temporary Health granted in addition to an Agent's normal +Health. Each grant remains distinct from later changes to the current Extra +Health total. _Avoid_: Health, healing, bonus armor + +**Hit Taken**: A hit received by an Agent, including one absorbed by Extra +Health. A Hit Taken does not require normal Health loss. _Avoid_: Taking Damage + +**Taking Damage**: A loss of an Agent's normal Health. A hit absorbed by Extra +Health does not count as Taking Damage. _Avoid_: Hit Taken diff --git a/docs/agents/domain.md b/docs/agents/domain.md new file mode 100644 index 0000000..609763e --- /dev/null +++ b/docs/agents/domain.md @@ -0,0 +1,60 @@ +# Domain docs + +Engineering skills must consult this repository's domain documentation before +exploring code. + +## Read before exploring + +- Read `CONTEXT.md` at the repository root. +- If `CONTEXT-MAP.md` exists, use it to find the `CONTEXT.md` files relevant to + the task. +- Read ADRs under `docs/adr/` that affect the area you will change. In a + multi-context repository, also check `src//docs/adr/`. + +If these files do not exist, proceed without comment. Do not suggest creating +them before the project resolves domain terms or architectural decisions. The +`/domain-modeling` skill, reached through `/grill-with-docs` and +`/improve-codebase-architecture`, creates them when needed. + +## File structure + +This repository uses the single-context layout: + +```text +/ +├── CONTEXT.md +├── docs/adr/ +│ ├── 0001-event-sourced-orders.md +│ └── 0002-postgres-for-write-model.md +└── src/ +``` + +A repository with multiple bounded contexts can use this layout: + +```text +/ +├── CONTEXT-MAP.md +├── docs/adr/ +└── src/ + ├── ordering/ + │ ├── CONTEXT.md + │ └── docs/adr/ + └── billing/ + ├── CONTEXT.md + └── docs/adr/ +``` + +## Use glossary terms + +Use the terms defined in `CONTEXT.md` in issue titles, refactor proposals, +hypotheses, and test names. Do not substitute synonyms that the glossary +rejects. + +If a needed concept is absent, reconsider whether the project uses that concept. +If it represents a real gap, record it for `/domain-modeling`. + +## Flag ADR conflicts + +Call out any proposal that conflicts with an ADR: + +> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_ diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md new file mode 100644 index 0000000..b410da9 --- /dev/null +++ b/docs/agents/issue-tracker.md @@ -0,0 +1,106 @@ +# Issue tracker: Gitea + +Issues and specs for this repo live as Gitea issues. Use the +[`tea`](https://gitea.com/gitea/tea) CLI for all operations. + +## Repository context + +Run commands inside the clone so `tea` can infer the repository and login from +its Git remote. If the clone has multiple Gitea remotes or logins, pass +`--remote ` or `--login `. Use `--repo /` only outside +the clone. + +Before the first operation, verify the instance with +`tea logins list --output json`. If it is missing, ask the user to run +`tea login add`; never ask for or handle their access token. + +## Conventions + +- **Create an issue**: `tea issues create --title "..." --description "..."`. + For a multi-line body, use shell command substitution around a quoted heredoc: + + ```bash + tea issues create --title "..." --description "$(cat <<'EOF' + Multi-line issue body. + EOF + )" + ``` + +- **Read an issue with comments**: + `tea issues --comments --fields index,state,author,url,title,body,assignees,labels,comments --output json`. +- **List issues**: + `tea issues list --state open --fields index,state,author,url,title,body,assignees,labels,comments --output json`, + adding `--labels "label-one,label-two"`, `--assignee `, or another + supported filter as needed. Paginate with `--page` and `--limit`; do not + assume the default first 30 results are complete. +- **Comment on an issue**: `tea comments add --description "..."`. +- **Apply or remove labels**: `tea issues edit --add-labels "..."` or + `--remove-labels "..."`. Separate multiple labels with commas. +- **Assign or unassign**: `tea issues edit --add-assignees "..."` or + `--remove-assignees "..."`. +- **Close**: post the closing explanation with + `tea comments add --description "..."`, then run + `tea issues close `. +- **Reopen**: `tea issues reopen `. +- **Raw API fallback**: use `tea api ''` only for a Gitea feature + without a first-class `tea` command. Prefer `{owner}` and `{repo}` + placeholders so repository context remains explicit. + +Use `--output json` for machine-readable reads. Do not scrape table output. + +## Pull requests as a triage surface + +**PRs as a request surface: no.** _(Set this to `yes` if this repo treats +external pull requests as feature requests; `/triage` reads this flag.)_ + +When set to `yes`, PRs use the same labels and states as issues: + +- **Read a PR with comments and diff**: + `tea pulls --comments --fields index,state,author,url,title,body,diff,assignees,labels,comments --output json`. +- **List open PRs**: + `tea pulls list --state open --fields index,state,author,author-id,url,title,body,assignees,labels,comments --output json`. + Determine whether an author is external from the repository's Gitea membership + data; the PR listing does not classify author membership. +- **Comment**: `tea comments add --description "..."`. +- **Apply or remove labels**: `tea pulls edit --add-labels "..."` or + `--remove-labels "..."`. +- **Close**: `tea pulls close `. + +Gitea pull requests use the repository's issue index space, so `#42` may refer +to either surface. If the context is unclear, inspect it with +`tea pulls 42 --output json`; if that command reports no PR, read it with +`tea issues 42 --output json`. + +## When a skill says "publish to the issue tracker" + +Create a Gitea issue with `tea issues create`. + +## When a skill says "fetch the relevant ticket" + +Run +`tea issues --comments --fields index,state,author,url,title,body,assignees,labels,comments --output json`. + +## Wayfinding operations + +`/wayfinder` uses one **map** issue with linked **child** issues. These +conventions store relationships in issue bodies, so they work across Gitea +versions. + +- **Map**: create one issue labelled `wayfinder:map` containing the Notes, + Decisions-so-far, and Fog sections. Use + `tea issues create --labels "wayfinder:map"` with its title and description. +- **Child ticket**: start the body with `Part of #` and apply a + `wayfinder:` label: `research`, `prototype`, `grilling`, or `task`. Add + each child as a task-list item in the map body to preserve frontier order. +- **Blocking**: put `Blocked by: #, #` near the top of the child body. A + ticket becomes unblocked after every referenced blocker closes. +- **Frontier query**: list all open children, order them by the map's task list, + and discard tickets with an open blocker or an assignee. Select the first + remaining ticket. Fetch each referenced blocker; do not infer its state from + map text. +- **Claim**: resolve the active username with `tea whoami`, then run + `tea issues edit --add-assignees ""` as the session's first + write. Do not assume `@me` works. +- **Resolve**: run `tea comments add --description ""`, close the + child with `tea issues close `, then append a context pointer and link to + the map's Decisions-so-far section. diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md new file mode 100644 index 0000000..046c565 --- /dev/null +++ b/docs/agents/triage-labels.md @@ -0,0 +1,14 @@ +# Triage labels + +Engineering skills use five canonical triage roles. This table maps each role to +the label string in this repository's issue tracker. + +| Canonical role | Tracker label | Meaning | +| ----------------- | ----------------- | -------------------------------------- | +| `needs-triage` | `needs-triage` | A maintainer must evaluate the issue | +| `needs-info` | `needs-info` | Waiting for more information | +| `ready-for-agent` | `ready-for-agent` | Fully specified and ready for an agent | +| `ready-for-human` | `ready-for-human` | Requires human implementation | +| `wontfix` | `wontfix` | Maintainers will not act on the issue | + +When a skill names a canonical role, use the corresponding tracker label.