@erclx/aitk 0.8.0

package/standards/readme.md

@@ -0,0 +1,163 @@
+---
+title: Readme reference
+description: Readme structure and content conventions
+---
+
+# Readme reference
+
+## Structure
+
+- H1 title, H2 major sections, H3 subsections. Maintain proper hierarchy for GitHub's auto-generated table of contents.
+- Use sentence case for all headings (proper nouns and product names retain their casing)
+- Project description in plain text directly under H1. Keep it to 2-3 sentences.
+- Do not create deeply nested heading structures that harm scannability
+- Do not use horizontal rules or dividers (`---`)
+
+## Sections
+
+- Required: project description, installation/setup, usage examples, support/help resources
+- Optional: badges (at top, before description), features, contributing (link to `CONTRIBUTING.md`), license (link to `LICENSE`)
+- Do not include full API documentation. Link to separate docs instead.
+- Do not include license text. Reference the `LICENSE` file.
+- Do not include detailed contribution guidelines. Reference `CONTRIBUTING.md`.
+- Do not include extensive troubleshooting guides. Use a wiki or separate documentation.
+
+## Content
+
+- Open public-facing READMEs with universal problems any reader recognizes, not repo-specific artifact names. Save artifact names for feature or "What is inside" sections.
+- Use relative paths for repository files. Use absolute URLs for external resources.
+- Include practical usage snippets for core functionality
+- For libraries/tools: include API quickstart
+- For applications/products: include usage instructions and configuration options
+- For CLI tools: include command examples with flags
+
+## Examples
+
+### Template
+
+````markdown
+# Project Name
+
+Brief description of what the project does in 2-3 sentences.
+
+## Features
+
+- Key feature highlighting user benefit
+- Key feature highlighting user benefit
+
+## Installation
+
+```bash
+npm install project-name
+```
+
+## Usage
+
+```javascript
+import { feature } from 'project-name'
+
+feature.doSomething()
+```
+
+## Documentation
+
+See the [full documentation](https://docs.example.com) for detailed API reference.
+
+## Support
+
+- Open an issue for bug reports
+- Check [existing issues](../../issues) before creating new ones
+
+## Contributing
+
+See the [contributing guidelines](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE)
+````
+
+### Correct
+
+````markdown
+# Auth SDK
+
+Lightweight authentication library for Node.js with OAuth2 and JWT support.
+
+## Features
+
+- OAuth2 provider integration (Google, GitHub, Azure)
+- JWT token generation and validation
+- Session management with Redis support
+- TypeScript support with full type definitions
+
+## Installation
+
+```bash
+npm install auth-sdk
+```
+
+## Quick start
+
+```javascript
+import { AuthClient } from 'auth-sdk'
+
+const client = new AuthClient({
+  provider: 'google',
+  clientId: process.env.CLIENT_ID,
+})
+
+const user = await client.authenticate(code)
+```
+
+## Documentation
+
+Visit [docs.auth-sdk.dev](https://docs.auth-sdk.dev) for full API reference.
+
+## Support
+
+- Report bugs via [GitHub Issues](../../issues)
+- Community support on [Discord](https://discord.gg/example)
+
+## License
+
+[MIT](LICENSE)
+````
+
+### Incorrect
+
+````markdown
+# Auth SDK
+
+This is a seamless and powerful authentication library that allows developers to easily integrate robust OAuth2 functionality.
+
+## Why Use This?
+
+Basically, this library is just amazing and will revolutionize how you handle auth.
+
+## Installation
+
+Simply run the following command to install:
+
+```bash
+npm install auth-sdk
+```
+
+## API Documentation
+
+### AuthClient Class
+
+#### Constructor
+
+constructor(options: AuthOptions)
+
+[...full API docs inline, should link to external docs...]
+
+## License
+
+MIT License
+
+Copyright (c) 2026 Example Corp
+
+[...full license text, should reference LICENSE file...]
+````

package/standards/requirements.md

@@ -0,0 +1,61 @@
+---
+title: Requirements reference
+description: Shape and content rules for .claude/REQUIREMENTS.md
+---
+
+# Requirements reference
+
+Applies to `.claude/REQUIREMENTS.md`. Describes what the product does and why, not how it works. Update when scope changes, goals shift, or a non-goal is promoted to a feature.
+
+## What goes in
+
+- The problem being solved and for whom
+- User-facing goals stated as outcomes, not implementation
+- Explicit non-goals that prevent feature creep. Mark deferred items "(deferred)" so they read as paused, not excluded.
+- MVP features as a numbered list: feature name and one-line description
+- Tech stack as a plain list of tools
+- Hard constraints that shape every decision
+
+## What does not go in
+
+- Implementation details, API names, or internal component references
+- Rationale for tech choices. That belongs in `.claude/ARCHITECTURE.md`.
+- Anything that describes how a feature is built rather than what it does
+
+## Sections
+
+Use `## Problem`, `## Goals`, `## Non-goals`, `## MVP features`, `## Tech stack`, and `## Constraints`. Add `## Distribution` when the rule below applies. Drop a section rather than pad it with filler.
+
+## Lifecycle
+
+The MVP list is a historical record of the original scope. Once those features ship it stays as written. Do not renumber it, do not append to it, and do not annotate entries with status. A reader telling the original scope apart from what followed depends on the first one staying legible.
+
+Later scope arrives as a new section rather than as an extension of the MVP list. Name the section for what it delivers and state its entries as outcomes, the same way the goals are stated. A roadmap sequences the MVP list alone, so a later scope section is sequenced by a fresh pass rather than folded into the roadmap that already shipped. The roadmap standard sends a project here once its last version ships, and this is the pass it means.
+
+## Distribution
+
+Include `## Distribution` only when the project ships to consumers outside its own repository. An internal service or a monorepo application has nothing to put in it, and a section every project is told to fill is one most projects pad. Place it after `## MVP features`.
+
+State each entry as an outcome the consumer reaches, never as the mechanism that delivers it. A registry name, a manifest format, a version scheme, or a release tool is implementation and belongs in `.claude/ARCHITECTURE.md`. Distribution pulls harder toward mechanism than any other section, which is why the rule is repeated here.
+
+## Template
+
+```markdown
+# Requirements
+
+## Problem
+
+## Goals
+
+## Non-goals
+
+## MVP features
+
+1. Feature: description
+
+<!-- ## Distribution: include only when shipping outside the repository -->
+
+## Tech stack
+
+## Constraints
+```

package/standards/rule.md

@@ -0,0 +1,79 @@
+---
+title: Governance rule reference
+description: Rule frontmatter, body shape, and voice for .claude/rules files
+---
+
+# Governance rule reference
+
+## Overview
+
+Rules give Claude Code coding constraints scoped to file paths. Claude Code discovers `.claude/rules/**/*.md` at session start. A rule with no `paths:` field always applies, at the same priority as `CLAUDE.md`. A rule with `paths:` applies when Claude reads a file matching the glob. Author one rule per topic so the scope stays precise.
+
+## Location
+
+- Rules live at `.claude/rules/<subdirectory>/<n>-<slug>.md`
+- Subdirectories group by domain: `core/`, `lang/`, `framework/`, `lib/`, `ui/`, `claude/`
+- `<n>` is a number in the subdirectory's band and `<slug>` is a one-to-three-word kebab topic
+- Scaffold a rule with a number that collides with neither the project's rules nor any installed shared rule set
+
+## Frontmatter
+
+- `description` (required): one line naming what the rule enforces and where
+- `paths` (optional): one glob per entry, for a rule scoped to a file set
+- Omit `paths` for an always-on rule that states a global principle with no file scope
+- Do not emit the legacy Cursor keys `globs`, `alwaysApply`, or `priority`. They are not read.
+
+```yaml
+---
+description: Enforce strict Python type hints, casing, and import patterns
+paths:
+  - '**/*.py'
+---
+```
+
+## Body
+
+- Open with an H1 `# <Topic> standards` in sentence case, then group rules under H2 sections. Proper nouns keep their casing (`# TypeScript standards`, `# Next.js standards`).
+- Use imperative voice for every rule (`Prefix booleans with is`, not `Booleans should be prefixed`)
+- State one rule per bullet as a single directive line
+- State what to do and what not to do. Do not explain the reasoning behind a rule.
+- Phrase a rule as a ban on the forbidden shape when it could otherwise enumerate allowed options, so it stays stable as categories grow
+- Cut any rule that resists crisp one-line phrasing. Vague guidance is worse than none.
+- Keep the file to one topic. A second topic is a second rule file.
+- Do not restate a rule that a sibling rule or `CLAUDE.md` already owns. Point once, never duplicate.
+
+## Examples
+
+### Correct
+
+```markdown
+---
+description: Enforce naming conventions for functions, booleans, and collections
+paths:
+  - '**/*.ts'
+---
+
+# Naming standards
+
+## Semantics
+
+- Prefix booleans with `is`, `has`, `should`, or `can`
+- Name functions as actions describing what they do
+- Name collections as plurals and items as singulars
+```
+
+### Incorrect
+
+```markdown
+---
+description: Naming
+globs: '**/*.ts'
+alwaysApply: false
+---
+
+# Naming
+
+Good naming matters because it makes code easier to read and maintain, so you
+should always pick descriptive names. Booleans are usually prefixed with is or
+has, and it can also be a good idea to think about collections too.
+```

package/standards/skill.md

@@ -0,0 +1,257 @@
+---
+title: Claude skill reference
+description: Claude skill structure and authoring rules
+---
+
+# Claude skill reference
+
+## Overview
+
+Skills give Claude Code domain-specific constraints and rules inline, so it can act immediately without reading all docs. Each skill body contains actionable rules for its domain. Full reference docs are the fallback for edge cases and deeper context. Skills use progressive disclosure: Claude reads only frontmatter at session start (~100 tokens each), matches a query against descriptions, then loads the full skill body.
+
+## Skill types
+
+Pick the type before writing. It decides the body shape.
+
+- Reference: conventions, patterns, and domain knowledge Claude applies inline. The body is rule bullets grouped by concern.
+- Task: step-by-step workflows Claude executes as actions. The body is numbered steps plus the rules constraining them.
+
+Reference template:
+
+```markdown
+---
+name: <skill-name>
+description: <what it does, when to use it, trigger phrases>
+---
+
+# <Topic>
+
+## <Concern group>
+
+- <actionable constraint>
+- <preference in X over Y form>
+```
+
+Task template:
+
+```markdown
+---
+name: <skill-name>
+description: <the action and when to use it>
+allowed-tools: <tools required>
+---
+
+# <Action name>
+
+## Steps
+
+1. <action>
+2. <action>
+
+## Rules
+
+- <constraint on how the steps run>
+- <constraint on output format>
+```
+
+## Structure
+
+- Skill is a folder named in kebab-case containing `SKILL.md` (required), `REQUIREMENT.md` (optional), `scripts/` (optional), `references/` (optional), `assets/` (optional)
+- `SKILL.md` must start with YAML frontmatter between `---` delimiters
+- No `README.md` inside the skill folder
+- No spaces, capitals, or underscores in folder or skill name
+
+## Requirement
+
+`REQUIREMENT.md` states what a skill is for, so a proposed change can be argued against something. This standard governs shape across the corpus and the requirement governs scope for one skill. Claude Code loads `SKILL.md` as the entry and ignores the sibling, so the file costs a target session nothing.
+
+Read it before editing the skill. When a change closes no gap the requirement states, change the requirement first or drop the change.
+
+Write the gaps from what the skill is for, then compare the body against them. Deriving the requirement from the body is circular, because a requirement reverse-engineered from an overfitted skill records the overfitting as the requirement.
+
+Not every skill needs one. A body short enough to read as its own specification already answers the questions below, and the file is worth writing when the skill's scope is arguable rather than obvious. Length is a weak proxy for that, since a short skill with a contested boundary earns one and a long skill doing one plain thing may not.
+
+### What a working requirement looks like
+
+A requirement works when a proposed change to the skill can be settled by reading it alone, without re-deriving what the skill is for:
+
+- Does this change close a gap the file states?
+- Does a line already in the body trace to one of those gaps?
+- Does this behavior belong to this skill or to a sibling the file names?
+
+A requirement that leaves any of the three open is non-conforming regardless of whether it satisfies every shape rule below. The third question is what makes a requirement worth more than a restated description, because a boundary stated only in prose is never checked against the skill on the other side of it.
+
+- State each gap as an observed failure, not an intent. "Without this skill a session invents its own filename" can be shown wrong. "This skill helps manage tasks" cannot fail, so it constrains nothing.
+- Trace everything under `## Must` to a stated gap. A `Must` with no gap behind it is the padding the file exists to prevent.
+- Keep it high level. A requirement that outgrows one file has stopped being a requirement, and `references/` already holds detail.
+- Use `name` and `description` frontmatter, matching `SKILL.md` so the pair is consistent.
+
+```markdown
+---
+name: <skill-name>
+description: <one line, distinct from the SKILL.md description>
+---
+
+# <Skill name> requirement
+
+## Gap
+
+Without this skill, a session <observed failure>, <observed failure>.
+
+## Must
+
+- <behavior that closes a named gap>
+
+## Must not
+
+- <behavior that would be wrong even though it closes a gap>
+
+## Guards
+
+- <the refusal condition and its message>
+
+## Out of scope
+
+- <the adjacent thing this deliberately does not cover, and what covers it>
+```
+
+## Frontmatter
+
+- `name` (required): kebab-case, matches folder name, no spaces or capitals
+- `description` (required): what it does + when to use it, under 1024 chars, no XML tags
+- `disable-model-invocation: true`: user-invoked only, Claude will not auto-trigger
+- `allowed-tools`: restrict tool access when the skill is active
+- `metadata`: optional key-value pairs (`author`, `version`, `mcp-server`)
+
+## Description
+
+- Structure: `[What it does] + [When to use it] + [Key trigger phrases]`
+- Include specific phrases users would say to trigger it
+- Be specific, not vague. Claude routes based on this field alone.
+- Add negative triggers if skill is over-triggering: `Do NOT use for X`
+
+## Body
+
+### Voice and headings
+
+- Use imperative voice throughout
+- Use sentence case for all headings (H1, H2, H3)
+
+### Rule content and scope
+
+- Front-load critical instructions
+- Contain only behavioral rules (what to do, what not to do) and pointers to reference docs. Narrative descriptions of what files are or how the system works belong in `docs/`, not in the skill body.
+- State rules, not inventories. Reference docs for lists that change, and phrase a rule as a ban on the forbidden shape rather than an enumeration of allowed options, so it stays stable as categories change.
+- Cut any rule that resists crisp one-line phrasing. Vague guidance is worse than none.
+- Group bullets under H2 headings by domain concern. Keep dos and don'ts together under the topic they belong to rather than splitting them into flat rules and constraints sections.
+- One actionable constraint per bullet. Prefer the `X over Y` form for preferences.
+- Do not include code examples unless a one to three line inline snippet captures a pattern the model cannot infer.
+- Do not duplicate general knowledge the model already has. Focus on project-specific conventions and preferences.
+
+### Progressive disclosure
+
+- Keep `SKILL.md` under 5,000 words. Move detailed docs to `references/`.
+- Use progressive disclosure: `SKILL.md` for core instructions, `references/` for detail, `scripts/` for deterministic operations
+- Link to `references/` files explicitly so Claude knows to load them
+
+### Reading and running commands
+
+- Reference a bundled `references/` or `scripts/` file with `${CLAUDE_SKILL_DIR}/<path>`, never a bare relative path. A bare path resolves against the session cwd and fails when a plugin skill runs from another project. `${CLAUDE_SKILL_DIR}` expands to the skill's own directory at render time and resolves from any cwd.
+- When referencing project files, include "from the project root" in the read instruction
+- When executing multiple independent operations (file reads, shell commands), run them in parallel to reduce latency
+
+### Anti-patterns to avoid
+
+- Avoid flags that dispatch between alternate flows. The model misreads them and runs the vanilla path. Dry-run-style toggles are fine. For alternate flows, prefer a separate skill or manual invocation of two skills in sequence.
+- When a skill should fire from multiple callers, rely on description matching with strong trigger phrases. Do not hardcode `Skill` calls in sibling skills that could trigger it naturally.
+- Before collapsing a manual multi-step flow into a skill, ask what the manual pauses do. Pauses that carry external timing, error-surfacing, or judgment weight are the feature. Prefer a snippet over a skill, or require explicit per-step confirmation.
+
+### Output and tuning
+
+- Skill success lines emit the full relative path from the project root (`<dir>/<file>`) for any file written, updated, or deleted. Bare filenames are not clickable in the terminal.
+- Codify a skill's posted or generated output as a fenced template, and keep the body consistent with every capability the frontmatter description names.
+- When a skill gathers user input or pre-seeds a template, attach a concrete proposed default to every question, derived from project context. Accept "use defaults" as a bulk-confirm.
+- Separate correctness axes (routing, sourcing, escalation, decline) from shape axes (line count, formatting, variant sprawl) when tuning a skill. Tighten only on correctness regressions. Do not convert soft caps to hard caps for aesthetic drift when correctness passes.
+
+## Scripts
+
+- Use `scripts/` for operations that must be deterministic or repetitive
+- Claude executes scripts and receives stdout. Scripts are not loaded into context.
+- Use XML tags in script output for reliable parsing: `<SECTION>content</SECTION>`
+- Use `#!/usr/bin/env bash` shebang
+- Always include `2>/dev/null || echo "FALLBACK"` guards on git and shell commands
+
+## Path resolution
+
+A skill reads from two roots. Know which one a file lives under before referencing it.
+
+- Bundled skill assets (`references/`, `scripts/`, `assets/`) resolve against the skill's own directory in the source clone. Reference them with `${CLAUDE_SKILL_DIR}/<path>`, never a bare relative path, so a plugin skill running from another project still finds them.
+- Installed shared docs (`.claude/rules/`, `.claude/context/`) resolve against the target project cwd, where install placed them. Reference them by that path.
+- Do not hand-copy a standard into a skill. A hand-copied file drifts from its source and belongs to no owner. If a skill must carry its own copy, generate it from the single source and reference it through `${CLAUDE_SKILL_DIR}`, so one owner keeps every copy in sync.
+
+### Citing a standard
+
+A standard reaches a skill by two routes, and a body that names only the first breaks in a project that installed the plugin without running `aitk standards install`.
+
+- Cite `.claude/standards/X.md` first, then name `${CLAUDE_SKILL_DIR}/../../standards/X.md` as the fallback. The plugin ships the whole standards folder beside `skills/`, so the second path resolves in every install.
+- The project copy wins when it exists, which keeps a target's local edits authoritative. The fallback only covers the case where the project lacks that file.
+- Condition the fallback on the standard, never on the `.claude/standards/` directory. `aitk standards sync` updates only filenames it already finds and never adds one, so a project that installed before a standard existed keeps the directory and never receives that file. A directory test passes there, no fallback engages, and the standard reads as absent.
+- State the fallback once per body, at the site that reads the standard. A later mention of a standard the body already read stays bare, since repeating the fallback at every mention is noise rather than instruction.
+- A guard on a standard's presence names the file and tests both paths before it stops. A guard that tests only `.claude/standards/` refuses to run in a plugin-only project that has the file, and a guard that tests the directory passes in the partial-install case it exists to catch.
+- Use `${CLAUDE_SKILL_DIR}`, never a bare `../../` and never `${CLAUDE_PLUGIN_ROOT}`. Only `${CLAUDE_SKILL_DIR}` is expanded before the body reaches the model. The other two leave the model to infer a base path, which it may resolve against the session cwd instead.
+
+## Invocation
+
+- Skills auto-trigger when Claude matches the request against the description
+- Invoke manually with `/skill-name` or `/<plugin>:skill-name` for plugin skills
+- Plugin skills are namespaced: `plugin-name:skill-name`
+- Priority order when names conflict: enterprise > personal > project > plugin
+
+## Execution
+
+- Task skills with preview+execute patterns must execute commands immediately after outputting the preview. Do not include "confirm before running" language or pause for user input.
+- Claude Code's tool permission dialog is the confirmation gate. The user hits Enter to approve or Escape to interrupt and revise.
+
+## Examples
+
+### Correct
+
+```markdown
+---
+name: code-review
+description: Reviews code for bugs, clarity, and standards compliance. Use when asking to review code, check a PR, or asking "does this look right".
+---
+
+# Code review
+
+Before reviewing, read from the project root:
+
+- `CLAUDE.md`: project conventions and behavior rules
+- `.claude/rules/`: path-scoped coding rules
+
+## Guards
+
+- If no file or diff is provided, stop: `❌ No code to review. Provide a file or diff.`
+
+## Response format
+
+- **Issues found:** <count>
+- **Summary:** <one line>
+
+List each issue with file, line, and suggested fix.
+```
+
+### Incorrect
+
+```markdown
+---
+name: code-review
+description: Handles all code-related tasks in scripts/, src/, and lib/. Also activate when user mentions bugs, refactoring, testing, linting, formatting, or any file ending in .ts .js .py .sh. # path-focused + keyword-stuffed
+---
+
+# Code review
+
+A good code review should check for bugs, performance issues, security vulnerabilities,
+code style, naming conventions, test coverage, documentation, error handling,
+edge cases, and adherence to SOLID principles... # dumps everything inline instead of referencing standards
+```