Packmind Create Standard

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