packmind-onboard

packmind-onboard

Action skill. Provides complete automated onboarding for Packmind:

1. Creates or selects a package
2. Analyzes codebase for patterns
3. Generates draft Standards and Commands
4. Creates items via CLI

Automatic package creation when none exist, user selection when packages are available.

Guarantees

• Read-only analysis. Analysis phase does not modify any project files.
• Drafts before creation. All items are written as drafts first, allowing review before creation.
• Preserve existing. Never overwrite existing artifacts. If a slug already exists, create -2, -3, etc.
• Evidence required. Every reported insight must include file-path evidence (and line ranges when feasible).
• Focused output. Max 5 Standards and 5 Commands generated per run.
• Graceful failure. Partial failures don't lose successful work; failed drafts are preserved.
• User control. When packages exist, users confirm package selection before creation.

Definitions

• Pattern (non-linter): a convention a linter cannot reliably enforce (module boundaries, cross-domain communication, workflow parity, error semantics, etc).
• Evidence: path[:line-line] entries; omit line ranges only when the file isn't text-searchable.

---

Step 0 — Introduction

Print exactly:

I'll start the Packmind onboarding process. I'll create your first standards and commands and send them to your Packmind organization. This usually takes ~3 minutes.

---

Step 1 — Get Repository Name

Get the repository name for package naming:

basename "$(git rev-parse --show-toplevel)"

Remember this as the repository name for package creation in Step 2.

Also run packmind-cli whoami and extract the Host: value from the output. Remember this URL for the completion summary.

---

Step 2 — Package Handling

Handle package creation or selection.

Check existing packages

List available packages:

packmind-cli install --list

Parse the output to get package names.

No packages exist

Auto-create package using repository name:

packmind-cli packages create "${REPO_NAME}-standards"

Print:

No existing packages found — created a new one: ${REPO_NAME}-standards

One package exists

Ask via AskUserQuestion:

• "Add to {package-name}?"
• "Create new package instead"

Multiple packages exist

Ask via AskUserQuestion:

• List each existing package as an option
• Include "Create new package" option

If "Create new package" is selected

• Ask for package name (suggest ${REPO_NAME}-standards as default)
• Run: packmind-cli packages create <name>

Remember the selected/created package name for later reference.

---

Step 3 — Announce

Print exactly:

packmind-onboard: analyzing codebase (read-only)
Target package: [package-name]

---

Step 4 — Detect Existing Packmind and Agent Configuration

Before analyzing, detect and preserve any existing Packmind/agent configuration.

Glob (broad, future-proof)

Glob for markdown in these roots (recursive):

• .packmind/**/*.md
• .claude/**/*.md
• .agents/**/*.md
• **/skills/**/*.md
• **/rules/**/*.md

Classify

Classify found files into counts:

• standards: .packmind/standards/**/*.md
• commands: .packmind/commands/**/*.md
• other_docs: any markdown under .claude/, .agents/, or any skills/ or rules/ directory outside .packmind

If any exist, print exactly:

Existing Packmind/agent docs detected:

    Standards: [N]

    Commands: [M]

    Other docs: [P]

No overwrites. New files (if you Export) will be added next to the existing ones.

---

Step 5 — Detect Project Stack (Minimal, Evidence-Based)

Language markers (check presence)

• JS/TS: package.json, pnpm-lock.yaml, yarn.lock, tsconfig.json
• Python: pyproject.toml, requirements.txt, setup.py
• Go: go.mod
• Rust: Cargo.toml
• Ruby: Gemfile
• JVM: pom.xml, build.gradle, build.gradle.kts
• .NET: *.csproj, *.sln
• PHP: composer.json

Architecture markers (check directories)

• Hexagonal/DDD: src/application/, src/domain/, src/infra/
• Layered/MVC: src/controllers/, src/services/
• Monorepo: packages/, apps/

Print exactly:

Stack detected (heuristic):

    Languages: [..]

    Repo shape: [monorepo|single]

    Architecture markers: [..|none]

---

Step 6 — Run Analyses

Read each reference file for detailed search patterns, thresholds, and insight templates.

Analysis	Reference File	Output focus
File Template Consistency	references/file-template-consistency.md	Commands
CI/Local Workflow Parity	references/ci-local-workflow-parity.md	Commands
Role Taxonomy Drift	references/role-taxonomy-drift.md	Standards
Test Data Construction	references/test-data-construction.md	Standards

Output schema (internal; do not print as-is to user)

For every finding, keep an internal record:

INSIGHT:
title: ...
why_it_matters: ...
confidence: [high|medium|low]
evidence:
- path[:line-line]
where_it_doesnt_apply:
- path[:line-line]

---

Step 7 — Generate All Drafts

Generate all draft files in one batch, using the formats defined above.

Standard Draft Format

For each Standard insight, create a Markdown file at .packmind/standards/_drafts/<slug>.draft.md:

# Standard Name

What the standard covers and why.

## Scope

Where this standard applies (e.g., 'TypeScript files', 'React components').

## Rules

### Rule starting with action verb

Another rule can follow...

## Examples

### Good

```typescript
// Valid code example
```

Bad

// Invalid code example

### Command Draft Format

For each Command insight, create a Markdown file at `.packmind/commands/_drafts/<slug>.draft.md`:

```markdown
# Command Name

What the command does, why it's useful, and when it's relevant.

## When to Use

- Scenario when this command applies
- Another scenario...

## Checkpoints

- Question to validate before proceeding?

## Steps

### 1. Step Name

What this step does and how to implement it.

```typescript
// Optional code example

2. Another Step

Description of next step...

### Generation Rules

- Generate drafts **only from discovered insights** (no invention)
- Use evidence from analysis to populate rules/steps
- Cap output: max **5 Standards** + **5 Commands**
- Never overwrite existing files; append `-2`, `-3`, etc. if slug exists

---

## Step 8 — Present Summary & Confirm

Present the generated draft files and ask for confirmation:

============================================================ ANALYSIS COMPLETE

Target package: [package-name] Stack detected: [languages], [monorepo?], [architecture markers] Analyses run: [N] checks

DRAFTS CREATED:

Standards ([N]):

1. [Name] → .packmind/standards/_drafts/[slug].draft.md
2. ...

Commands ([M]):

1. [Name] → .packmind/commands/_drafts/[slug].draft.md
2. ...

Drafts are saved in .packmind/*/_drafts/ — you can review or edit them before creating.

Then ask via AskUserQuestion with three options:

- **Create all now** — Proceed with creating all standards and commands
- **Let me review drafts first** — Pause to allow editing, re-run skill when ready
- **Cancel** — Exit without creating anything

---

## Step 9 — Create Items

### If user selected "Create all now"

**IMPORTANT:** The CLI only accepts JSON playbook files, not markdown. Before calling the CLI, convert each `.draft.md` file to a `.json` file.

#### Standard JSON Schema

Convert the markdown draft to this JSON format:

```json
{
  "name": "Standard name (from # heading)",
  "description": "What the standard covers (from intro paragraph)",
  "scope": "Where it applies (from ## Scope section)",
  "rules": [
    {
      "content": "Rule starting with action verb (from ### Rule headings under ## Rules)",
      "examples": {
        "positive": "Valid code example (from ### Good section)",
        "negative": "Invalid code example (from ### Bad section)",
        "language": "TYPESCRIPT"
      }
    }
  ]
}

Command JSON Schema

Convert the markdown draft to this JSON format:

{
  "name": "Command name (from # heading)",
  "summary": "What it does and when (from intro paragraph)",
  "whenToUse": ["Scenario 1", "Scenario 2 (from ## When to Use bullets)"],
  "contextValidationCheckpoints": ["Question 1? (from ## Checkpoints bullets)"],
  "steps": [
    {
      "name": "Step name (from ### N. Step Name)",
      "description": "Step description (from step content)",
      "codeSnippet": "Optional code fence content"
    }
  ]
}

Conversion and Creation Process

For each standard draft:

1. Read the .draft.md file
2. Convert to JSON matching the schema above
3. Write the JSON to .packmind/standards/_drafts/<slug>.json
4. Run CLI command to create:

packmind-cli standards create .packmind/standards/_drafts/<slug>.json

5. If creation succeeded, add to package:

packmind-cli packages add --to <package-slug> --standard <slug>

6. Track result (success/failure)

For each command draft:

1. Read the .draft.md file
2. Convert to JSON matching the schema above
3. Write the JSON to .packmind/commands/_drafts/<slug>.json
4. Run CLI command to create:

packmind-cli commands create .packmind/commands/_drafts/<slug>.json

5. If creation succeeded, add to package:

packmind-cli packages add --to <package-slug> --command <slug>

6. Track result (success/failure)

Show progress:

Sending standards and commands to your Packmind organization...
✓ error-handling-pattern
✓ naming-conventions
✗

---

*Content truncated.*