packmind-create-standard

name	packmind-create-standard
description	Guide for creating coding standards via the Packmind CLI. This skill should be used when users want to create a new coding standard (or add rules to an existing standard) that captures team conventions, best practices, or coding guidelines for distribution to GitLab Duo.
license	Complete terms in LICENSE.txt
metadata	{"packmind-cli-version":"< 0.25.0"}

Standard Creator

This skill provides a complete walkthrough for creating coding standards via the Packmind CLI.

About Coding Standards

Coding standards are collections of rules that capture team conventions, best practices, and coding guidelines. They help maintain consistency across codebases and enable GitLab Duo to follow your team's specific practices.

What Standards Provide

1. Consistent code style - Rules that enforce naming conventions, formatting, and structure
2. Best practices - Guidelines for error handling, testing, security, and performance
3. Domain knowledge - Company-specific patterns, architectural decisions, and business logic
4. Code examples - Positive/negative examples that demonstrate correct vs incorrect usage

Standard Structure

Every standard is drafted as a markdown file with this structure:

# Standard Name

## Description

What the standard covers and why.

## Scope

Comma-separated glob patterns for files where the standard applies (e.g., "**/*.ts", "**/*.spec.ts,**/*.test.ts").

## Rules

### Rule description starting with action verb

#### Positive Example

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

#### Negative Example

\`\`\`typescript
// Invalid code example
\`\`\`

### Another rule without examples

Naming Guidelines

The # Title heading is the display name shown in indexes and dashboards. The slug is auto-generated from it — never write the slug yourself.

Format: Use Title Case with spaces — natural language, not a slug.

• Capitalize each significant word
• Use spaces between words, never hyphens or underscores
• Be descriptive and specific (2–5 words) — indicate the domain/technology and the aspect covered

Examples:

• ✅ "TypeScript Testing Conventions", "React Component File Organization", "Backend Error Handling"
• ❌ "typescript-testing-conventions" (slug format — use Title Case with spaces)
• ❌ "testing" (too generic)
• ❌ "good-practices" (slug format and too vague)
• ❌ "Standards for Code" (describes meta-concept, not the actual domain)

Note: The summary field is used in other workflows but not yet supported by the CLI.

Understanding scope vs summary

• scope (required by CLI): WHERE the standard applies — comma-separated glob patterns.
  • Must be glob patterns only — never natural language descriptions.
  • Examples: "**/*.spec.ts,**/*.test.ts", "**/*.tsx,**/*.jsx", "src/domain/**/*.ts"
  • Common patterns:
    • **/*.ts — all TypeScript files
    • **/*.spec.ts,**/*.test.ts — all test files
    • **/*.tsx,**/*.jsx — all React component files
    • src/domain/**/*.ts — domain TypeScript files under src
    • packages/**/src/**/*.ts — all package source files
  • ⚠️ Never write natural language like "TypeScript files" or "React components" — the value is used as literal glob patterns for file matching, so natural language will match nothing.
• summary (optional, not yet CLI-supported): WHEN/WHY to apply - high-level purpose and trigger condition
  • Examples: "Apply when writing tests to ensure consistency", "Use when handling user data for privacy compliance"

Prerequisites

Before creating a standard, verify that packmind-cli is available:

Check if packmind-cli is installed:

packmind-cli --version

If not available, install it:

npm install -g @packmind/cli

Then login to Packmind:

packmind-cli login

Standard Creation Process

To create a standard, follow this process in order, skipping steps only if there is a clear reason why they are not applicable.

Step 1: Clarify the Request

Gather essential information before drafting the standard.

Clarification Flow

Study the user's request and identify critical gaps. The number of questions should match the request clarity:

• 1-2 questions when the request is well-defined (clear scope, specific examples, detailed context)
• 3-5 questions when the context is unclear or the request is vague

Examples of focused questions:

• "Which service or file shows the expected pattern?"
• "Is there an existing doc or rule we must stay aligned with?"
• "What specific aspect matters most (mocking guidelines, naming conventions, assertion style)?"

Introduce questions with a simple phrase about needing clarification, then list as bullet points—no numbering, no category headers.

Repository Access Guardrail

Do not open or scan repository files unless the user explicitly points to them (provides file paths or requests project-wide review). If source references are needed, ask the user to supply them.

What to Capture

Take brief notes on:

• Title or slug (if mentioned)
• Scope guardrails
• Key references
• Expected outcomes

Keep notes concise—just enough to unlock drafting.

Step 2: Draft Standard in Markdown

Transform the understanding into a complete markdown draft with rules and examples.

Draft Creation

1. Create a draft markdown file in .packmind/standards/_drafts/ (create the folder if missing) using filename <slug>.md (lowercase with hyphens)
2. Draft structure:
   • # <Standard Title> (Title Case, 2–5 words)
   • ## Description — what the standard covers and why it exists
   • ## Scope — comma-separated glob patterns (required)
   • ## Rules — each rule as a ### <rule text> subsection following the Rule Writing Guidelines below
   • For each rule that benefits from code examples, add:
     • #### Positive Example with a language-annotated code block showing the compliant approach
     • #### Negative Example with a language-annotated code block showing the anti-pattern
   • If a rule doesn't benefit from code examples (e.g., process or organizational rules), skip examples for that rule

This draft file is the only file created during drafting — no separate files are needed.

Rule Writing Guidelines

Each rule should follow these format requirements:

1. Start with an action verb - Use imperative form (e.g., "Use", "Avoid", "Prefer", "Include")
2. Be concise - Max ~25 words per rule
3. Be specific and actionable - Avoid vague guidance
4. Focus on one concept - One rule per convention

Avoid Rationale Phrases

Rules describe WHAT to do, not WHY. Strip justifications and benefits—let examples demonstrate value.

Common fluff patterns to remove:

• "to improve/provide/ensure..." (benefit phrases)
• "while maintaining/preserving..." (secondary concerns)
• "for better/enhanced..." (quality claims)
• "and enable/allow..." (future benefits)

Bad (includes rationale):

Document props with JSDoc comments to provide IDE intellisense and improve developer experience.

Good (action only):

Document component props with JSDoc comments (/** ... */) describing purpose, expected values, and defaults.

Rule Splitting

If a rule addresses 2+ distinct concerns, proactively split it into separate rules:

Bad (too broad):

Create centralized color constants in dedicated files for consistent palettes, using semantic naming based on purpose rather than specific color values.

Good (split into focused rules):

• Define color constants in theme/colors.ts using semantic names (e.g., primary, error)
• Use semantic color tokens instead of literal hex values in components

Inline Examples in Rules

Inline examples (code, paths, patterns) within the rule content are optional. Only include them when they clarify something not obvious from the rule text.

Types of useful inline examples:

• Code syntax: const, async/await, /** ... */
• File paths: infra/repositories/, domain/entities/
• Naming patterns: .spec.ts, I{Name} prefix

Good rules with inline examples:

• "Use const instead of let for variables that are never reassigned"
• "Prefix interface names with I (e.g., IUserService)"
• "Place repository implementations in infra/repositories/"

Good rules without inline examples:

• "Name root describe block after the class or function under test"
• "Run linting before committing changes"
• "Keep business logic out of controllers"

Bad rules:

• "Write good code" (too vague)
• "Use const and prefix interfaces with I" (multiple concepts)
• "Don't use var" (no positive guidance)

Examples Guidelines

• Examples should be realistic and directly relevant to this codebase
• Each example should clearly demonstrate why the rule matters
• Keep code snippets minimal—only include what's necessary to illustrate the point
• Annotate every code block with its language (e.g., typescript, sql, javascript)

Valid language values for code blocks:

• TYPESCRIPT, TYPESCRIPT_TSX
• JAVASCRIPT, JAVASCRIPT_JSX
• PYTHON, JAVA, GO, RUST, CSHARP
• PHP, RUBY, KOTLIN, SWIFT, DART, SQL
• HTML, CSS, SCSS, YAML, JSON
• MARKDOWN, BASH, GENERIC

Draft Summary

After saving the draft file, write a concise summary that captures:

• One sentence summarizing the standard's purpose
• A bullet list of all rules (each rule ~22 words max, imperative form, with inline code if helpful)

Then proceed directly to Step 3.

Step 3: Review Before Submission

Before running the CLI command, you MUST get explicit user approval:

1. Display a formatted recap of the standard content:

---
Name: <standard name>

Description: <description>

Scope: <scope>

Rules:

1. <rule content>
   - ✅ <positive example>
   - ❌ <negative example>
2. <rule content>
   - ✅ <positive example>
   - ❌ <negative example>
...
---

2. Provide the file path to the markdown file so users can open and edit it directly if needed.

3. Ask: "Here is the standard that will be created on Packmind. The draft file is at <path> if you want to review or edit it. Do you approve?"

4. Wait for explicit user confirmation before proceeding to Step 4.

5. If the user requests changes, go back to earlier steps to make adjustments.

Step 4: Confirm and Submit

1. Re-read the markdown file from disk to capture any user edits.

2. Compare with the original content you created in Step 2.

3. If changes were detected:

   • Display the formatted recap again (same format as Step 3)
   • Ask: "The file was modified. Here is the updated content that will be sent. Do you confirm?"
   • Wait for explicit confirmation before proceeding.

4. If no changes: Proceed directly to submission.

5. Convert the markdown to JSON using these conversion rules:

   • # heading → name
   • ## Description content → description
   • ## Scope content → scope
   • Each ### ... under ## Rules → rule content
   • #### Positive Example code block → examples.positive
   • #### Negative Example code block → examples.negative
   • Code fence language identifier → examples.language (UPPERCASED)

   Important: examples is a single object (not an array) — one positive/negative pair per rule. It is optional — omit entirely for rules without code examples. When present, all three fields (positive, negative, language) are required.

   Expected JSON format:

   {
     "name": "Standard Name",
     "description": "What the standard covers and why.",
     "scope": "**/*.spec.ts,**/*.test.ts",
      
       
          
          
            
            
            
         
       
       
          
       
     
   
   

packmind-cli standards create --origin-skill packmind-create-standard <<'EOF'
{"name":"...","description":"...","scope":"...","rules":[...]}
EOF

Expected output on success:

packmind-cli Standard "Your Standard Name" created successfully (ID: <uuid>)

Troubleshooting

"Not logged in" error:

packmind-cli login

"Failed to resolve global space" error:

• Verify your API key is valid
• Check network connectivity to Packmind server

Validation errors:

• Ensure all required sections are present in the markdown file
• Check that the ## Rules section has at least one ### rule subsection
• Verify code blocks have language annotations

"expected object, received array" error on examples:

• The examples field must be a single object {positive, negative, language}, not an array
• Each rule supports at most one example pair

Step 5: Cleanup

After the standard is successfully created, delete the draft markdown file in .packmind/standards/_drafts/.

Only clean up on success - if the CLI command fails, keep the files so the user can retry.

Step 6: Offer to Add to Package

After successful creation, check if the standard fits an existing package:

1. Run packmind-cli install --list to get available packages
2. If no packages exist, skip this step silently and end the workflow
3. Analyze the created standard's name, description, and scope against each package's name and description
4. If a package is a clear semantic fit (the standard's domain/technology aligns with the package's purpose):
   • Present to user: "This standard seems to fit the <package-slug> package."
   • Offer three options:
     • Add to <package-slug>
     • Choose a different package
     • Skip
5. If no clear fit is found, skip silently (do not mention packages)
6. If user chooses to add:
   • Run: packmind-cli packages add --to <package-slug> --standard <standard-slug>
   • Ask: "Would you like me to run packmind-cli install to sync the changes?"
   • If yes, run: packmind-cli install

Complete Example

Here's a complete example creating a TypeScript testing standard:

File: .packmind/standards/_drafts/testing-conventions.md

# TypeScript Testing Conventions

## Description

Enforce consistent testing patterns in TypeScript test files to improve readability, maintainability, and reliability of the test suite.

## Scope

**/*.spec.ts,**/*.test.ts

## Rules

### Use descriptive test names that explain the expected behavior

#### Positive Example

\`\`\`typescript
it('returns empty array when no items match filter')
\`\`\`

#### Negative Example

\`\`\`typescript
it('test filter')
\`\`\`

### Follow Arrange-Act-Assert pattern in test structure

#### Positive Example

\`\`\`typescript
const input = createInput();
const result = processInput(input);
expect(result).toEqual(expected);
\`\`\`

#### Negative Example

\`\`\`typescript
expect(processInput(createInput())).toEqual(expected);
\`\`\`

### Use one assertion per test for better error isolation

#### Positive Example

\`\`\`typescript
it('validates name', () => { expect(result.name).toBe('test'); });
it('validates age', () => { expect(result.age).toBe(25); });
\`\`\`

#### Negative Example

\`\`\`typescript
it('validates user', () => { expect(result.name).toBe('test'); expect(result.age).toBe(25); });
\`\`\`

### Avoid using 'should' at the start of test names - use assertive verb-first naming

Creating the standard (piped via stdin):

packmind-cli standards create --origin-skill packmind-create-standard <<'EOF'
{"name":"TypeScript Testing Conventions","description":"Enforce consistent testing patterns...","scope":"**/*.spec.ts,**/*.test.ts","rules":[...]}
EOF

Quick Reference

Section	Required	Description
# Title	Yes	Title Case, descriptive, 2–5 words
## Description	Yes	What and why
## Scope	Yes (CLI)	Comma-separated glob patterns
## Rules	Yes	Contains rule subsections
### Rule text	Yes (≥1)	Rule text (verb-first, max ~25 words)
#### Positive Example	No	Valid code in fenced block
#### Negative Example	No	Invalid code in fenced block