@h1v35/hivex 0.2.2 → 0.3.0

package/skills/hivex/references/markdown.md

@@ -1,24 +1,24 @@
-# Optional Markdown convention
+# Recommended Markdown foundation
 
-Use the project's existing Markdown as it is. Hivex must not require this convention, frontmatter, numbered ADRs or a particular directory structure. Recommend these practices when adopting Hivex or writing documentation, without repeatedly proposing a migration of an established project.
+Use this foundation when adopting Hivex. Prefer migration to its standard structure when reasonably possible, preserving and completing useful existing documents, their authority, history and links. Hivex's knowledge reader continues to accept other Markdown layouts; document organization is not an ingestion prerequisite.
 
-These practices draw on established authority-map and documentation-layout patterns and the domain-modeling skill. They preserve useful documentation discipline without prescribing retired machinery from any one project.
+The foundation combines a clear authority map, project purpose, domain language and maintainable decisions. The bundled documentation skill guides adoption and completion; no retired planning framework or external skill set is required.
 
 ## Give knowledge one authoritative home
 
-Keep shared decisions at project or monorepo level. Package-specific or module-specific knowledge can stay with that package or module. Link shared rules instead of copying them into each area. Folders and files appear only when there is useful content to put in them.
+Keep shared decisions at project or monorepo level. Package-specific or module-specific knowledge can stay with that package or module. Link shared rules instead of copying them into each area. Initialization prepares the core documents and directories. Complete project-specific drafts from evidence and the owner, and add further documents only for useful distinct purposes.
 
 A useful catalogue distinguishes:
 
 - An authority map explaining where each kind of knowledge belongs.
+- A PRD recording purpose, problem, vision, users and scope.
 - A domain glossary defining the project's terms, with avoided synonyms where useful.
 - Decisions and their reasons, often kept as ADRs.
 - Guidelines containing design invariants and lessons worth applying again.
-- Process documents explaining the working method.
 - Procedures for concrete operational or recovery tasks.
 - Research and evidence identified as dated support, not automatically current decisions.
 
-For example, a project may use `docs/README.md`, `docs/CONTEXT.md`, `docs/adr/`, `docs/guidelines/`, `docs/procedures/` and `docs/research/`. Keep standing rules and design guidance in `guidelines`, and instructions for carrying out tasks in `procedures`; avoid overlapping directories with indistinct purposes. These are examples, not required paths. Multiple bounded contexts may have their own glossary and decisions with a small context map linking them; a monorepo need not duplicate one shared product glossary.
+For example, a project may use `docs/README.md`, `docs/CONTEXT.md`, `docs/adr/`, `docs/guidelines/`, `docs/procedures/` and `docs/research/`. Keep standing rules and design guidance in `guidelines`, and instructions for carrying out tasks in `procedures`; avoid overlapping directories with indistinct purposes. These are the adoption defaults; an existing project may retain another arrangement where migration would not be appropriate. Multiple bounded contexts may have their own glossary and decisions with a small context map linking them; a monorepo need not duplicate one shared product glossary.
 
 ## Write decisions for the next reader
 
@@ -40,10 +40,16 @@ Use an ADR when the choice is consequential, reflects a real trade-off and would
 
 When replaced text obscures a decision's current meaning, preserve that history in a clearly marked Markdown archive and keep the active document focused on applicable rules, reasons, dependencies and exceptions. A wholly superseded ADR can remain as a short pointer to its replacement and archive. Preserve referenced anchors or update their links. Do not archive a live exception merely because it is old, or change what an earlier decision meant while shortening its current presentation.
 
-A project may use `docs/archive/adr/` for this purpose; other layouts remain valid. Historical evidence should be available for focused consultation without being loaded into every model context. Declare its relative globs in `hivex.json` under `history`, then use the installed CLI's `--source` selection or a known relationship for bounded retrieval. Compaction must not silently make necessary evidence inaccessible. The human or implementing agent maintains these documents; Hivex does not rewrite or move the sources.
+A project may use `docs/archive/adr/` for this purpose; other layouts remain valid. Historical evidence should be available for focused consultation without being loaded into every model context. Declare its relative globs in `hivex.json` under `history`, then use the installed CLI's `--source` selection or a known relationship for bounded retrieval. Compaction must not silently make necessary evidence inaccessible. The principal agent maintains and migrates the documents. The CLI prepares missing foundation files and explicitly relocates derived graph references; it does not decide new product doctrine or silently rename existing sources.
 
 ## Keep the glossary focused
 
 Define each project-specific concept briefly and use that term consistently. A glossary explains what a concept is; it is not an implementation manual, task plan or collection of general programming terms. Group related concepts when it helps and link context-specific definitions instead of copying.
 
 Code and executable contracts explain mechanics. Markdown preserves the intent, constraints, decisions and reasons that code cannot explain. Update that knowledge alongside the change rather than leaving the only explanation in a conversation or private agent memory.
+
+## Keep the agent entrypoint small
+
+Use a short `AGENTS.md` with orientation and knowledge pointers, development/verification guidance and project-specific constraints only where needed. Link the relevant authority with enough context to know when it matters. Do not duplicate the PRD, glossary or guidelines, or require every document on every task.
+
+The public [AGENTS.md convention](https://agents.md/) is ordinary Markdown without required fields. The foundation supplies a consistent starting shape rather than another schema or a line-count gate.

package/skills/hivex-design/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: hivex-design
+description: Resolve open product or architectural decisions, investigate uncertainty, and shape work into a useful specification or execution slices. Use for planning, a grill, design tradeoffs, focused research, or prototypes that answer a question.
+---
+
+# Design useful work
+
+Recover the request, existing decisions and relevant project vocabulary first. Use the project's Markdown and Hivex's local retrieval. Inspect facts available in the repository or authoritative sources instead of asking the owner to rediscover them.
+
+If the task is already defined, carry that scope into implementation. Do not start an interview or create planning artifacts merely to satisfy a pipeline.
+
+## Resolve what is open
+
+For a grill, ask one meaningful question at a time, explain the practical tradeoff and give a recommendation. Follow dependencies between decisions and wait for the owner's answer. Reuse prior answers. Close the shared understanding before implementing a design the owner is still deciding.
+
+Research a factual uncertainty using relevant primary sources. Build a small disposable prototype when seeing or exercising a behavior is the cheapest way to resolve a question. Keep either activity bounded to the decision it serves; preserve the useful conclusion and its evidence.
+
+Use the project's language and domain responsibilities. Prefer a small interface that hides meaningful internal complexity. Respect established architecture and identify concrete tradeoffs before introducing another abstraction.
+
+## Make execution clear
+
+Capture the intended outcome, scope, useful acceptance evidence and unresolved decisions at the level the change needs. Reuse an existing issue or spec when it already owns the work. Create extra execution tickets only for independently verifiable slices or dependencies that help coordination.
+
+A cross-layer feature slice should deliver a meaningful result. A mechanical refactor may need a different sequence; choose it from the actual affected code rather than forcing a template. Do not require exhaustive user stories, a decision-map hierarchy or one ticket per agent session.
+
+Record durable decisions through the project's documentation practice, using `hivex-document` when maintaining that knowledge. Use `hivex-git` for tracker publication within the owner's authorization.

package/skills/hivex-document/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: hivex-document
+description: Establish or maintain project purpose, domain language, decisions, guidelines and procedures. Use for Hivex adoption, documentation migration, PRDs, glossaries, ADRs, or recording durable project knowledge.
+---
+
+# Maintain the project's knowledge
+
+Start with the project's documentation map, relevant sources and current owner decisions. Markdown owns intent and reasons; the graph helps recover them. Update the document that already owns the topic and scope. Create another only for a distinct purpose.
+
+## Adopt the foundation
+
+Use the installed `hivex init` when available to prepare missing documents and configuration. The CLI scaffolds files; the principal agent completes their meaning. Read its report before continuing. Do not invent a project's vision, requirements or domain terms to fill a template.
+
+Prefer migration to Hivex's standard structure when reasonably possible, preserving useful content, history, authority and links. Keep knowledge at its monorepo, package or module scope. Inspect existing instructions and source selection before moving files; when graph sources move, use the supported `hivex snapshot relocate` operation and normal incremental maintenance.
+
+Complete the PRD and glossary from existing evidence and the owner. Ask only for essential open decisions. Keep unresolved sections explicitly provisional, and finish meaningful content before spending calls to index empty scaffolding.
+
+Use the foundation [document templates](../hivex/assets/project/docs/README.md) as starting material. Apply the project's own product, stack and operating details; do not import another repository's identities, host paths or historical authorizations.
+
+## Give each document a purpose
+
+- PRD: why the project exists, who it serves, its vision, intended outcomes and scope.
+- CONTEXT: agreed domain terms with concise definitions; resolve ambiguity without adding a generic programming glossary.
+- ADR: a decision and its rationale, scope, alternatives or exceptions when they matter to future work.
+- Guideline: maintained rules for ongoing work.
+- Procedure: enough context, steps and verification to perform a particular operation. Add prerequisites or recovery details when they are relevant.
+
+Keep rules with their conditions and exceptions. An accepted status or a historical quotation does not settle a later replacement. When a decision changes, make the change and history traceable; move replaced detail to an archive when that helps keep the current authority usable.
+
+## Keep AGENTS.md lean
+
+Follow the open AGENTS.md convention with a consistent small entrypoint: orientation and knowledge pointers, development/verification guidance, and project-specific constraints only when needed. The [foundation entrypoint](../hivex/assets/project/AGENTS.md) provides the starting shape.
+
+Do not duplicate the PRD, glossary, guidelines or skills. A pointer should say when its target matters, not require every document on every task. Add local instructions only for real scope-specific needs. Use no arbitrary line-count gate.
+
+After documentation changes, check affected links and source selection. Use Hivex's installed maintenance and snapshot capabilities when knowledge changes, preserving existing work and accounting. Check the relevant sources before treating a graph warning as a new product decision.

package/skills/hivex-git/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: hivex-git
+description: Manage issue triage, execution tickets, branches, commits, pull requests, CI follow-through and merge conflicts under the project's conventions and existing authorization.
+---
+
+# Keep work and Git coherent
+
+Read the repository's tracker and Git conventions, relevant issue and current working state. Preserve unrelated work. Use the configured tracker and native Git capabilities; do not introduce an orchestration framework to coordinate ordinary changes.
+
+## Triage and plan execution
+
+Reuse an existing issue when its scope fits. Capture a clear outcome, boundaries and useful acceptance evidence. Split work only when independent results or actual dependencies make it easier to execute. Read-only retrieval does not need a new issue.
+
+Use the project's triage guide. For an adopter without one, the [foundation triage guide](../hivex/assets/project/docs/guidelines/triage-labels.md) defines the baseline. Readiness, expected owner involvement, dependencies and risk are different dimensions; none selects a model or grants permission.
+
+When adopting or aligning labels, use the [common catalogue](assets/labels.json) as the starting set and compare the live catalogue with the documented meaning. Preserve useful project-specific areas and reconcile aliases without losing issue classification. The shared names `epic`, `research`, `prototype` and `decision` describe work independently of a skill. The catalogue also identifies known legacy aliases. If a replacement label already exists, transfer useful issue classification before retiring the alias; do not discard dependencies or change issue scope. Retire a generic task label only when the remaining labels and issue retain its useful meaning.
+
+Use native blocking/sub-issue relationships when they help coordination. Do not create a decision-map hierarchy for already defined work or declare something ready merely because a label is present.
+
+## Commit and open a PR
+
+Start a coherent branch from the current integration branch, following the project's naming conventions. Use its commit format and language; Conventional Commits are a useful default. Check the diff and the relevant verification before publishing the branch.
+
+Keep the PR focused and linked to its owning issue. Lead with the concrete problem and resulting behavior, then the validation and material limits. Use a structured body argument or body file for multiline text. Follow the project's readiness convention for drafts.
+
+Track CI to an actual result. Fix demonstrated problems within scope, and preserve an honest distinction between failure, omission and success. Confirm that the independent review is current and uses the implementation agent's model and effort. Reuse a valid completed review instead of starting another; do not infer approval from an automated knowledge report.
+
+## Integrate and clean up
+
+Merge when the required checks and review pass and the owner's existing authorization covers the action. Do not ask for the same authorization again; if a tool blocks an otherwise authorized action, explain the actual blocker and prepare the concrete result before asking for what is missing.
+
+When resolving conflicts, read both changes and their intent, preserve needed behavior and run the checks affected by the resolution. Do not choose one side blindly or overwrite unrelated work.
+
+Preserve shared history and avoid direct integration-branch pushes or force pushes. After integration, update the appropriate checkout safely.
+
+## Finish the branch lifecycle
+
+Clean up the local and remote branches and worktrees belonging to completed work. For implementation work, establish that the intended changes were integrated. Research, evidence and prototype branches may have a different end state: preserve their useful results and required history in project documentation or an appropriate archive before retiring a completed branch.
+
+Keep unfinished work, including research, evidence and prototypes that have not reached their intended outcome. Branch age, absence of a PR or absence of an open issue is not enough to establish completion. Inspect the associated work and its disposition; leave uncertain or unrelated branches intact instead of treating cleanup as a repository-wide purge.
+
+Do not discard unmerged work merely to bypass a Git deletion refusal. Establish that it is integrated, its needed results/history are preserved, or discarding it is covered by the owner's explicit authorization. Preserve knowledge and required evidence before cleaning local execution state.

package/skills/hivex-git/assets/labels.json

@@ -0,0 +1,152 @@
+{
+  "labels": [
+    {
+      "name": "needs-triage",
+      "color": "d4c5f9",
+      "description": "The issue needs evaluation."
+    },
+    {
+      "name": "needs-info",
+      "color": "fbca04",
+      "description": "Essential information is missing."
+    },
+    {
+      "name": "ready-for-agent",
+      "color": "2ea44f",
+      "description": "Defined enough for an agent to begin; later decisions may still arise."
+    },
+    {
+      "name": "ready-for-human",
+      "color": "1d76db",
+      "description": "The work requires human implementation."
+    },
+    {
+      "name": "wontfix",
+      "color": "ffffff",
+      "description": "This issue will not be actioned."
+    },
+    {
+      "name": "AFK",
+      "color": "1a7f37",
+      "description": "Can finish without further owner participation; not a permission or model choice."
+    },
+    {
+      "name": "HITL",
+      "color": "0052cc",
+      "description": "Owner participation is expected before completion; not a model choice."
+    },
+    {
+      "name": "blocked",
+      "color": "e11d21",
+      "description": "Blocked by a dependency or unresolved decision."
+    },
+    {
+      "name": "deferred",
+      "color": "fbca04",
+      "description": "Decided, but intentionally not scheduled."
+    },
+    {
+      "name": "high-risk",
+      "color": "b60205",
+      "description": "Consequential change requiring particular review attention."
+    },
+    {
+      "name": "bug",
+      "color": "d73a4a",
+      "description": "Supported behavior is not working correctly."
+    },
+    {
+      "name": "enhancement",
+      "color": "a2eeef",
+      "description": "New or improved capability."
+    },
+    {
+      "name": "documentation",
+      "color": "0075ca",
+      "description": "Project documentation work."
+    },
+    {
+      "name": "refactor",
+      "color": "5319e7",
+      "description": "Code or structure changes preserving intended behavior."
+    },
+    {
+      "name": "testing",
+      "color": "0e8a16",
+      "description": "Test infrastructure or useful behavior coverage."
+    },
+    {
+      "name": "architecture",
+      "color": "0e8a16",
+      "description": "Domain model or architectural decisions."
+    },
+    {
+      "name": "security",
+      "color": "b60205",
+      "description": "Security findings or hardening."
+    },
+    {
+      "name": "performance",
+      "color": "d93f0b",
+      "description": "Performance, resource use or caching."
+    },
+    {
+      "name": "ci",
+      "color": "0366d6",
+      "description": "CI, build tooling or repository configuration."
+    },
+    {
+      "name": "ux/ui",
+      "color": "d4c5f9",
+      "description": "User-facing experience or interface behavior."
+    },
+    {
+      "name": "epic",
+      "color": "3e2f8c",
+      "description": "Coherent parent work tracking related child issues."
+    },
+    {
+      "name": "research",
+      "color": "0e8a16",
+      "description": "Investigate facts needed for a decision."
+    },
+    {
+      "name": "prototype",
+      "color": "fbca04",
+      "description": "A bounded experiment to resolve a design question."
+    },
+    {
+      "name": "decision",
+      "color": "d93f0b",
+      "description": "An unresolved product or engineering decision."
+    },
+    {
+      "name": "severity: critical",
+      "color": "b60205",
+      "description": "Security finding severity: critical."
+    },
+    {
+      "name": "severity: high",
+      "color": "d93f0b",
+      "description": "Security finding severity: high."
+    },
+    {
+      "name": "severity: moderate",
+      "color": "fbca04",
+      "description": "Security finding severity: moderate."
+    },
+    {
+      "name": "severity: low",
+      "color": "c2e0c6",
+      "description": "Security finding severity: low."
+    }
+  ],
+  "legacyAliases": {
+    "wayfinder:map": "epic",
+    "wayfinder:research": "research",
+    "wayfinder:prototype": "prototype",
+    "wayfinder:grilling": "decision",
+    "risk: high": "high-risk"
+  },
+  "retired": ["wayfinder:task"]
+}

package/skills/hivex-implement/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: hivex-implement
+description: Implement a defined change, diagnose a bug, or refactor code with focused verification and review. Use when work is ready to execute; use design support only for decisions that remain open.
+---
+
+# Implement the intended change
+
+Recover the request, the owning issue when present, and relevant project decisions. Use Hivex's local search, neighbors and sources as needed. Carry settled scope forward; raise a question only when the evidence leaves a consequential decision open.
+
+Follow the repository's engineering guideline, domain language and actual module boundaries. Prefer a direct solution, existing capability or standard library before adding layers, dependencies or speculative flexibility. Keep responsibility for the integrated result when delegating suitable bounded subtasks.
+
+For a bug, establish the failing behavior and inspect the relevant path before changing code. Use observations to distinguish causes. Keep a reproduction or regression test when its value justifies its maintenance; do not accumulate broad diagnostics or unrelated fixes.
+
+## Choose useful verification
+
+Prioritize critical flows, stable rules and regressions. Use TDD when the behavior is sufficiently defined and it helps the task, rather than as a universal sequence. Explore or clarify open behavior before locking assumptions into tests.
+
+Test observable results through meaningful interfaces with independent expected values. Avoid tests coupled to private helpers or arbitrary structure. Investigate a failure against the intended contract; do not mechanically preserve a bad test or change a test merely to make it pass.
+
+Run the repository checks that apply to the changed surfaces. Broaden checks when a change, failure or unresolved concern warrants it. Report actual results and material limits without repeating checks that remain valid.
+
+Update the owning Markdown for durable decisions, keeping conditions and exceptions. Use `hivex-document` when that work needs documentation support.
+
+## Finish the work
+
+Use one independent `hivex-review` pass by default. Supply the intended scope, relevant authorities and the implementation agent's actual model and effort so the reviewer matches them. Add another review only for a concrete reason. Resolve findings on their merits.
+
+Use `hivex-git` to complete the authorized commit, PR and CI work. Preserve existing owner authorization and make any remaining dependency or required user action explicit.

package/skills/hivex-review/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: hivex-review
+description: Independently review a change or pull request for intended scope, correctness and project standards, with relevant decision dependencies and exceptions. Use for implementation review or a review requested against a commit, branch or diff.
+---
+
+# Review the actual change
+
+Establish the comparison base, reviewed revision and intended outcome. Read the relevant issue or specification and affected project authorities. Review the diff and the context necessary to understand its behavior; reuse prior findings and verification that still apply.
+
+Use one independent reviewer by default. If you are already assigned as that reviewer, perform the review directly; do not spawn another review pass. Its model and reasoning effort must match the implementation agent's profile. Pass the profile explicitly when defaults differ and verify the effective profile through the available tools. Do not substitute the knowledge model for this review. If independent review cannot be performed, say what remains unreviewed.
+
+## Check the whole result
+
+Assess the intended scope, behavior, regressions and the standards relevant to this repository. Focus on concrete problems and simpler solutions that materially improve correctness or maintenance. Do not manufacture findings from stylistic preferences already handled by the configured tools.
+
+Use Hivex's local retrieval and source reading for decisions, dependencies, exceptions and replacements. Ask for model-assisted knowledge review only when it contributes information the review needs. Confirm its findings against the actual sources and code; it is support for the principal review, not a replacement.
+
+Evaluate whether the checks protect meaningful behavior and whether their evidence covers the change. Do not require TDD, a test for every edit, or implementation-shaped assertions. Distinguish an unverified outcome from a demonstrated defect.
+
+## Report and follow through
+
+Report actionable findings with their location, impact and supporting evidence. Explain technical details clearly when needed to understand the problem. State a clean result when there are no justified findings, together with material verification limits.
+
+A later change invalidates only the affected conclusions. Review that delta instead of repeating the entire review without cause. Add another independent pass when concrete risk or findings justify it, preserving the required model/effort profile.
+
+Resolve adverse findings by evidence or correction, not repeated attempts to obtain approval. A review result does not grant merge or publication permission; existing owner authorization and repository requirements still govern those actions.

package/src/cli.ts

@@ -3,6 +3,7 @@ import { checkReview } from './review.ts';
 import { documentCommand } from './documents.ts';
 import { knowledgeMaintenance } from './knowledge-maintenance.ts';
 import { knowledgeCommand } from './knowledge.ts';
+import { projectInitializationCommand } from './project-initialization.ts';
 import { snapshotCommand } from './snapshot-command.ts';
 import { diagnostic } from './cli/diagnostic.ts';
 
@@ -70,6 +71,7 @@ const main = async (input: string[]) => {
           usage: 'snapshot export | import | relocate <from> <to> [--root <project>]',
         },
         { modelCalls: 0, name: 'status', usage: 'status [--root <project>]' },
+        { modelCalls: 0, name: 'init', usage: 'init [--root <project>]' },
       ],
       configuration:
         'Optional hivex.json with include/exclude/history relative Markdown globs; history sources are focused evidence.',
@@ -87,6 +89,9 @@ const main = async (input: string[]) => {
   if (input[0] === 'snapshot') {
     return snapshotCommand(input);
   }
+  if (input[0] === 'init') {
+    return projectInitializationCommand(input);
+  }
   if (input[0] === 'recover' || input[0] === 'prune') {
     return knowledgeMaintenance(input);
   }