⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v3.2.0

hardshell

asistent-alex@asistent-alex⭐ 1 stars· last commit 6mo ago· 0 open issues

Apply when writing, reviewing, refactoring, or designing any code.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐ 1 on GitHubGitHub ↗

New / niche

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Hardshell - OpenClaw Coding Standards

Version: 3.2.0

A comprehensive coding standards skill for OpenClaw agents. Apply every rule on every coding task, without exception.

Installation

# Install from ClawHub (when published)
openclaw skill install hardshell

# Or install from GitHub
openclaw skill install https://github.com/asistent-alex/openclaw-hardshell

What It Covers

Security (Highest Priority)

  • Input validation and trust boundaries
  • Secrets and credentials management
  • Authentication and authorization
  • Common vulnerabilities (SQLi, XSS, CSRF, SSRF, path traversal)
  • API and HTTP security
  • Dependency auditing

Architecture & Design

  • SOLID principles
  • Separation of concerns
  • Law of Demeter
  • API design patterns
  • Error handling strategies

Code Quality

  • Naming conventions
  • Function design
  • Comments and documentation
  • Code smells to avoid

Testing

  • TDD (Test-Driven Development)
  • Test pyramid (70% unit, 20% integration, 10% E2E)
  • Coverage minimums (70% on business logic)
  • Test isolation rules

Git Workflow

  • Branch strategy (trunk-based with short-lived feature branches)
  • Conventional commits format
  • PR process and code review

Performance

  • Complexity analysis
  • Caching strategies
  • Optimization guidelines

Agent Behavior

  • Think before coding — surface assumptions and tradeoffs
  • Simplicity first — minimum code, nothing speculative
  • Surgical changes — touch only what you must
  • Goal-driven execution — define verifiable success criteria

Usage

When the agent is working on code, it automatically loads relevant reference files:

User: "Write a Python function to send email"
Agent: Loads references/languages/python.md for Python-specific standards

When editing existing code or receiving an ambiguous request:

Agent: Loads references/agent-behavior.md for surgical change rules

Reference Files

FilePurpose
references/agent-behavior.mdBehavioral guidelines for LLM coding agents
references/git-workflow.mdBranches, commits, PRs
references/performance.mdComplexity, caching
references/skill-development.mdStandards for creating OpenClaw skills
references/testing.mdTDD, test pyramid
references/languages/python.mdPython-specific
references/languages/typescript.mdTS/JS-specific
references/languages/go.mdGo-specific

Validation

Run the smoke test after any change:

bash scripts/validate.sh

Changelog

See CHANGELOG.md for version history.

License

MIT License - see LICENSE

Contributing

This skill is designed to be universal. If you have improvements that apply across all OpenClaw skills:

  1. Fork the repository
  2. Create a feature branch
  3. Submit a pull request with your improvements

Author

OpenClaw Community

Acknowledgments

The agent behavior guidelines in references/agent-behavior.md are derived from Andrej Karpathy's observations on LLM coding pitfalls, implemented via the community skill multica-ai/andrej-karpathy-skills.

Links

// HOW IT'S BUILT

// FILES

17 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • SKILL.md8.7 KB98e41fefa9c0upstream ↗
    ---
    name: hardshell
    version: 3.2.0
    description: Apply when writing, reviewing, refactoring, or designing any code.
    tags: [security, architecture, clean-code, coding, code-review, testing, git, performance]
    always: false
    user-invocable: true
    validation: scripts/validate.sh
    ---
    
    # Hardshell — code quality standards
    
    Apply every rule below on every coding task, without exception.
    If the model supports extended thinking, activate it for architecture decisions.
    
    ## Reference files — load when relevant
    
    - Git workflow, commits, PRs → read `references/git-workflow.md`
    - Performance, complexity, caching → read `references/performance.md`
    - Testing strategy and TDD → read `references/testing.md`
    - Python project → read `references/languages/python.md`
    - TypeScript / JavaScript project → read `references/languages/typescript.md`
    - Go project → read `references/languages/go.md`
    - Creating or modifying skills → read `references/skill-development.md`
    - Agent behavior, surgical changes, assumption surfacing → read `references/agent-behavior.md`
    
    Load the relevant file before responding on that topic.
    Do not load files unless the task requires them.
    
    ---
    
    ## 1. Security (highest priority)
    
    ### Input & trust boundary
    - Validate all external input at the entry point. Never trust it downstream.
    - Use allowlists, not denylists.
    - Sanitize output to prevent injection (XSS, HTML, shell, SQL).
    - Validate file uploads: type, size, extension.
    
    ### Secrets & credentials
    - Zero secrets in source code. No keys, tokens, or passwords — ever.
    - Use environment variables or a secrets manager.
    - Add secret files to `.gitignore` immediately.
    - Rotate any secret that was ever committed.
    
    ### Authentication & authorization
    - Never implement your own crypto. Use established libraries.
    - Hash passwords with bcrypt, argon2, or scrypt. Never SHA-* alone.
    - Check authorization on every action — never assume it from a prior step.
    - Apply Principle of Least Privilege everywhere.
    
    ### Common vulnerabilities — always prevent
    - SQL injection: parameterized queries only, never string interpolation.
    - XSS: escape output, use Content-Security-Policy headers.
    - CSRF: use tokens or SameSite cookies.
    - SSRF: validate and allowlist URLs before server-side requests.
    - Path traversal: never concatenate user input into file paths.
    - Sensitive data in logs: scrub passwords, tokens, PII before logging.
    
    ### API & HTTP
    - Always use HTTPS. Redirect HTTP → HTTPS.
    - Set security headers: HSTS, X-Content-Type-Options, X-Frame-Options, CSP.
    - Rate-limit authentication endpoints.
    - Return generic error messages to clients. Never expose stack traces.
    - Use 401 for unauthenticated, 403 for unauthorized — never confuse them.
    
    ### Dependencies
    - Audit dependencies regularly using the tool standard for the language.
    - Pin versions in production. Remove unused packages promptly.
    
    ---
    
    ## 2. Architecture & design
    
    ### Core principles (apply all)
    - Single Responsibility: one module/class = one reason to change.
    - Open/Closed: open for extension, closed for modification.
    - Liskov Substitution: subtypes must fully replace their base types.
    - Interface Segregation: prefer small focused interfaces over large general ones.
    - Dependency Inversion: depend on abstractions, not concretions. Inject dependencies.
    - Separation of Concerns: UI, business logic, and data access must never be mixed.
    - Law of Demeter: a module should not reach into the internals of objects it uses.
    
    ### Layered architecture — always enforce
    ```
    Entry layer (routes, controllers, CLI)  →  input handling only
    Service / use-case layer                →  business logic only
    Repository / data-access layer          →  persistence only
    Domain / model layer                    →  data shape only
    ```
    A controller must never contain business logic.
    A repository must never call another service.
    
    ### Modules & dependencies
    - Loosely coupled, highly cohesive.
    - Dependency direction: outer layers depend on inner, never the reverse.
    - Prefer composition over inheritance.
    - Circular dependencies are a design smell — fix the design.
    - Each module exposes a clean, documented public interface.
    
    ### Design patterns — when to use
    - Factory: object creation is complex or type-dependent.
    - Strategy: behavior varies and you need runtime swapping.
    - Repository: always abstract data access behind an interface.
    - Observer: decoupled side effects (notifications, audit logs).
    - Adapter: wrap third-party libraries so they can be swapped later.
    - Facade: simplify a complex subsystem with a clean surface.
    - Do not add patterns speculatively. Add them when the problem is already present.
    
    ### Database & persistence
    - Never build queries via string interpolation. Use parameterized queries or an ORM.
    - Keep migrations versioned and reversible.
    - Use transactions for multi-step writes.
    - Avoid N+1 queries — use joins or eager loading where appropriate.
    
    ---
    
    ## 3. Clean code
    
    ### Naming
    - Names must reveal intent: `getUserById` not `getData`, `isActive` not `flag`.
    - Functions: verb + noun. Variables: noun. Booleans: question form.
    - No unexplained abbreviations. `url`, `id`, `http` are fine. `usrCnt` is not.
    - Adapt conventions to the project's language and existing style.
    
    ### Functions
    - One function = one thing. If you need "and" to describe it, split it.
    - Keep functions short. If it exceeds ~25 lines, extract sub-functions.
    - Max 3 parameters. More than 3 → group into a config/options object.
    - No hidden side effects unless the name makes it explicit.
    - Return early (guard clauses) to avoid deep nesting.
    
    ### Variables & state
    - Prefer immutable declarations. Avoid mutable state unless necessary.
    - Declare variables close to where they are used.
    - No magic numbers. Extract named constants with clear intent.
    
    ### Error handling
    - Never swallow errors silently. An empty catch block is forbidden.
    - Log the original error with context before re-throwing or returning.
    - Use typed/custom error classes for domain-specific errors.
    - User-facing messages must be helpful and must not leak internals.
    
    ### Comments & documentation
    - Self-documenting code first. A comment explaining *what* means the code is unclear.
    - Comments explain *why*, not what.
    - Document all public functions and exported interfaces.
    - Remove commented-out dead code before committing.
    
    ### Style & duplication
    - No duplicate code. If you write something twice, extract it.
    - DRY — but don't over-abstract. Only generalize what already repeats.
    - YAGNI — don't add code for hypothetical future needs.
    - Respect the project's existing style. Consistency beats preference.
    
    ---
    
    ## 4. Review checklist
    
    Run before completing any coding task.
    
    **Correctness**
    - Does the code do exactly what was asked?
    - Are edge cases handled: empty input, null, zero, max values, concurrency?
    - Are errors handled and logged with context?
    
    **Security**
    - Is all input validated at the boundary?
    - Are there secrets or credentials in the code or comments?
    - Are all queries parameterized?
    - Is authorization checked on every action?
    - Can user input reach a dangerous operation (path, query, shell, deserialization)?
    
    **Architecture**
    - Does it respect the layer separation defined in section 2?
    - Are dependencies pointing in the correct direction?
    - Is the module's public API clean and minimal?
    
    **Clean code**
    - Are all names intention-revealing?
    - Are functions small with single responsibility?
    - Is there duplicated logic that should be extracted?
    - Are magic numbers replaced with named constants?
    
    **Tests**
    - Is there a test for the happy path?
    - Are edge cases and error paths tested?
    - Do tests assert actual behavior, not just absence of exceptions?
    
    ---
    
    ## 5. Agent behavior rules
    
    - Apply sections 1–3 on every coding task without being asked.
    - Run section 4 checklist before completing any task.
    - When editing existing code or receiving an ambiguous request, read `references/agent-behavior.md` first.
    - Load the relevant `references/` file when the task involves git, testing,
      performance, a specific language, or skill development.
    - **When loading or using a skill:**
      - Read SKILL.md first (it's the contract)
      - If `validation:` field exists, run it before using the skill
      - If no validation script, do a basic smoke test
      - If something doesn't work as documented, fix it before proceeding
      - Never assume a skill works without verification
    - Flag issues with these prefixes:
      - **🔴 SECURITY** — explain why dangerous and show the fix.
      - **🟡 ARCHITECTURE** — name the pattern that resolves it.
      - **🔵 CLEAN CODE** — show the improved version.
      - **🟠 PROCESS** — git, testing, or performance issue.
    - Always show improved code, not just observations.
    - Never sacrifice security for convenience. If the user insists, comply only for
      explicit local prototypes and add: `TODO: SECURITY — remove before production`.
    
  • README.md3.3 KB9714b81801a4upstream ↗
    # Hardshell - OpenClaw Coding Standards
    
    **Version:** 3.2.0
    
    A comprehensive coding standards skill for OpenClaw agents. Apply every rule on every coding task, without exception.
    
    ## Installation
    
    ```bash
    # Install from ClawHub (when published)
    openclaw skill install hardshell
    
    # Or install from GitHub
    openclaw skill install https://github.com/asistent-alex/openclaw-hardshell
    ```
    
    ## What It Covers
    
    ### Security (Highest Priority)
    - Input validation and trust boundaries
    - Secrets and credentials management
    - Authentication and authorization
    - Common vulnerabilities (SQLi, XSS, CSRF, SSRF, path traversal)
    - API and HTTP security
    - Dependency auditing
    
    ### Architecture & Design
    - SOLID principles
    - Separation of concerns
    - Law of Demeter
    - API design patterns
    - Error handling strategies
    
    ### Code Quality
    - Naming conventions
    - Function design
    - Comments and documentation
    - Code smells to avoid
    
    ### Testing
    - TDD (Test-Driven Development)
    - Test pyramid (70% unit, 20% integration, 10% E2E)
    - Coverage minimums (70% on business logic)
    - Test isolation rules
    
    ### Git Workflow
    - Branch strategy (trunk-based with short-lived feature branches)
    - Conventional commits format
    - PR process and code review
    
    ### Performance
    - Complexity analysis
    - Caching strategies
    - Optimization guidelines
    
    ### Agent Behavior
    - Think before coding — surface assumptions and tradeoffs
    - Simplicity first — minimum code, nothing speculative
    - Surgical changes — touch only what you must
    - Goal-driven execution — define verifiable success criteria
    
    ## Usage
    
    When the agent is working on code, it automatically loads relevant reference files:
    
    ```
    User: "Write a Python function to send email"
    Agent: Loads references/languages/python.md for Python-specific standards
    ```
    
    When editing existing code or receiving an ambiguous request:
    
    ```
    Agent: Loads references/agent-behavior.md for surgical change rules
    ```
    
    ## Reference Files
    
    | File | Purpose |
    |------|---------|
    | `references/agent-behavior.md` | Behavioral guidelines for LLM coding agents |
    | `references/git-workflow.md` | Branches, commits, PRs |
    | `references/performance.md` | Complexity, caching |
    | `references/skill-development.md` | Standards for creating OpenClaw skills |
    | `references/testing.md` | TDD, test pyramid |
    | `references/languages/python.md` | Python-specific |
    | `references/languages/typescript.md` | TS/JS-specific |
    | `references/languages/go.md` | Go-specific |
    
    ## Validation
    
    Run the smoke test after any change:
    
    ```bash
    bash scripts/validate.sh
    ```
    
    ## Changelog
    
    See [CHANGELOG.md](CHANGELOG.md) for version history.
    
    ## License
    
    MIT License - see [LICENSE](LICENSE)
    
    ## Contributing
    
    This skill is designed to be universal. If you have improvements that apply across all OpenClaw skills:
    
    1. Fork the repository
    2. Create a feature branch
    3. Submit a pull request with your improvements
    
    ## Author
    
    OpenClaw Community
    
    ## Acknowledgments
    
    The agent behavior guidelines in `references/agent-behavior.md` are derived from [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls, implemented via the community skill [`multica-ai/andrej-karpathy-skills`](https://github.com/multica-ai/andrej-karpathy-skills).
    
    ## Links
    
    - [OpenClaw Documentation](https://docs.openclaw.ai)
    - [ClawHub](https://clawhub.ai)
    - [GitHub Repository](https://github.com/asistent-alex/openclaw-hardshell)
    
  • scripts/validate.sh1.9 KB35d848c5ee89upstream ↗
    #!/bin/bash
    # validate.sh — smoke test for the hardshell skill
    # Verifies SKILL.md is present, parseable, and that no legacy CLAUDE.md exists.
    
    set -e
    
    REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
    cd "$REPO_ROOT"
    
    echo "🔍 Validating hardshell skill..."
    
    # 1. SKILL.md exists and has required fields
    if [ ! -f SKILL.md ]; then
      echo "❌ SKILL.md not found"
      exit 1
    fi
    
    NAME=$(grep -m1 '^name:' SKILL.md | sed 's/^name:[[:space:]]*//')
    VERSION=$(grep -m1 '^version:' SKILL.md | sed 's/^version:[[:space:]]*//')
    
    if [ -z "$NAME" ] || [ -z "$VERSION" ]; then
      echo "❌ SKILL.md missing name or version"
      exit 1
    fi
    echo "  ✅ SKILL.md: name=$NAME version=$VERSION"
    
    # 2. No legacy CLAUDE.md
    if [ -f CLAUDE.md ]; then
      echo "❌ Legacy CLAUDE.md found — conventions should live in SKILL.md"
      exit 1
    fi
    echo "  ✅ No legacy CLAUDE.md"
    
    # 3. No .claude/ directory tracked by git
    if git ls-files .claude/ | grep -q . 2>/dev/null; then
      echo "❌ .claude/ directory is tracked by git — should be gitignored"
      exit 1
    fi
    echo "  ✅ .claude/ not tracked"
    
    # 4. All reference files exist
    REFS=("references/agent-behavior.md" "references/git-workflow.md" "references/performance.md" "references/testing.md" "references/skill-development.md" "references/languages/python.md" "references/languages/typescript.md" "references/languages/go.md")
    for ref in "${REFS[@]}"; do
      if [ ! -f "$ref" ]; then
        echo "❌ Missing reference: $ref"
        exit 1
      fi
    done
    echo "  ✅ All reference files present (${#REFS[@]})"
    
    # 5. No 'Claude' mentions in tracked files (case-insensitive)
    if git grep -qi 'claude' -- "$(git ls-files)" 2>/dev/null; then
      echo "⚠️  Found 'Claude' mentions in tracked files (review if intentional):"
      git grep -in 'claude' -- "$(git ls-files)" 2>/dev/null || true
    else
      echo "  ✅ No 'Claude' mentions in tracked files"
    fi
    
    echo ""
    echo "✅ All validations passed — $NAME v$VERSION is clean"
  • references/agent-behavior.md4.7 KB33d0c886b213upstream ↗
    # Agent behavior guidelines
    
    Behavioral guidelines to reduce common LLM coding mistakes.
    Derived from [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876) and the community skill `andrej-karpathy-skills`.
    Use these when writing, reviewing, or editing code to avoid overcomplication, make surgical changes, surface assumptions, and define verifiable success criteria.
    
    These rules complement `SKILL.md` sections 1–4 (Security, Architecture, Clean Code).
    They address *how the agent thinks and acts* while coding, not *what the code does*.
    
    **Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
    
    ---
    
    ## 1. Think Before Coding
    
    🔵 **CLEAN CODE** — Don't assume. Don't hide confusion. Surface tradeoffs.
    
    Before implementing, the agent must:
    - State assumptions explicitly. If uncertain, ask.
    - Present multiple interpretations — don't pick silently when ambiguity exists.
    - If a simpler approach exists, say so. Push back when warranted.
    - If something is unclear, stop. Name what's confusing. Ask.
    
    **❌ Wrong:**
    ```
    User: "Add caching for the user lookup."
    Agent: <implements Redis cluster with 200 lines>
    ```
    
    **✅ Right:**
    ```
    User: "Add caching for the user lookup."
    Agent: "Assumptions: I'll use in-memory caching since this is a single-node
      deployment. If multi-node later, we should switch to Redis.
      Alternative: memoize with a TTL decorator.
      Proceed with in-memory + TTL?"
    ```
    
    ---
    
    ## 2. Simplicity First
    
    🔵 **CLEAN CODE** — Minimum code that solves the problem. Nothing speculative.
    
    - No features beyond what was asked.
    - No abstractions for single-use code.
    - No "flexibility" or "configurability" that wasn't requested.
    - No error handling for impossible scenarios.
    - If you write 200 lines and it could be 50, rewrite it.
    
    The test: *Would a senior engineer say this is overcomplicated?* If yes, simplify.
    
    **❌ Wrong:**
    ```python
    class AbstractUserCacheStrategyFactory(ABC):
        ...  # 80 lines for a dict-based cache that was asked for
    ```
    
    **✅ Right:**
    ```python
    from functools import lru_cache
    
    @lru_cache(maxsize=128)
    def get_user_by_id(user_id: int) -> User:
        return db.query(User).get(user_id)
    ```
    
    ---
    
    ## 3. Surgical Changes
    
    🟠 **PROCESS** — Touch only what you must. Clean up only your own mess.
    
    When editing existing code:
    - Don't "improve" adjacent code, comments, or formatting.
    - Don't refactor things that aren't broken.
    - Match existing style, even if you'd do it differently.
    - If you notice unrelated dead code, mention it — don't delete it.
    
    When your changes create orphans:
    - Remove imports / variables / functions that **YOUR changes** made unused.
    - Don't remove pre-existing dead code unless asked.
    
    The test: *Every changed line should trace directly to the user's request.*
    
    **❌ Wrong:**
    ```diff
    - def get_user(id):
    + def get_user(user_id):          # ← requested
          # TODO: clean this up later  # ← unrelated change
    -     return db.get(id)
    +     return db.get(user_id)      # ← requested
    +                                   # ← also reformatted entire file
    ```
    
    **✅ Right:**
    ```diff
    - def get_user(id):
    + def get_user(user_id):
    -     return db.get(id)
    +     return db.get(user_id)
    ```
    
    ---
    
    ## 4. Goal-Driven Execution
    
    🟠 **PROCESS** — Define success criteria. Loop until verified.
    
    Transform imperative tasks into verifiable goals:
    
    | Instead of... | Transform to... |
    |---|---|
    | "Add validation" | "Write tests for invalid inputs, then make them pass" |
    | "Fix the bug" | "Write a test that reproduces it, then make it pass" |
    | "Refactor X" | "Ensure tests pass before and after" |
    | "Add feature Y" | "Add Y with tests, verify no regressions" |
    
    For multi-step tasks, state a brief plan:
    ```
    1. [Step] → verify: [check]
    2. [Step] → verify: [check]
    3. [Step] → verify: [check]
    ```
    
    Strong success criteria let the agent loop independently.
    Weak criteria ("make it work") require constant clarification.
    
    ---
    
    ## Cross-references to hardshell
    
    | Agent behavior rule | Maps to hardshell SKILL.md |
    |---|---|
    | §1 Think Before Coding | §3 Clean Code — "Comments explain why, not what" |
    | §2 Simplicity First | §3 Clean Code — "DRY / YAGNI / no duplicate code" |
    | §3 Surgical Changes | §4 Review Checklist — "Does it do exactly what was asked?" |
    | §4 Goal-Driven Execution | §4 Review Checklist — "Tests / happy path / edge cases" + `references/testing.md` |
    
    ---
    
    ## When these guidelines are working
    
    You will see:
    - Fewer unnecessary changes in diffs — only requested changes appear.
    - Fewer rewrites due to overcomplication — code is simple the first time.
    - Clarifying questions come before implementation — not after mistakes.
    - Clean, minimal PRs — no drive-by refactoring or "improvements".
    
  • references/git-workflow.md3.9 KB90cd2d356d5aupstream ↗
    # Git workflow standards
    
    Load this file when the task involves commits, branches, PRs, or code review process.
    
    ---
    
    ## Branch strategy
    
    Use a consistent branching model. Recommended: trunk-based with short-lived feature branches.
    
    ```
    main          →  always deployable, protected
    develop       →  integration branch (optional, for teams with release cycles)
    feature/<id>-<slug>   →  e.g. feature/142-user-auth
    fix/<id>-<slug>       →  e.g. fix/198-null-pointer-login
    chore/<slug>          →  e.g. chore/upgrade-dependencies
    release/<version>     →  e.g. release/2.1.0
    hotfix/<slug>         →  branched from main, merged back to main and develop
    ```
    
    Rules:
    - Feature branches live max 1–2 days. Longer → split the work.
    - Never commit directly to `main` or `develop`.
    - Delete branches after merging.
    - One concern per branch. Mixing features and fixes makes review harder.
    
    ---
    
    ## Conventional commits
    
    Format: `<type>(<scope>): <short description>`
    
    Types:
    - `feat`: new feature (triggers minor version bump)
    - `fix`: bug fix (triggers patch version bump)
    - `chore`: maintenance, deps, tooling (no version bump)
    - `refactor`: code restructure without behavior change
    - `test`: adding or fixing tests
    - `docs`: documentation only
    - `perf`: performance improvement
    - `ci`: CI/CD configuration changes
    - `revert`: reverting a previous commit
    
    Rules:
    - Description in imperative mood: "add user auth" not "added user auth".
    - Max 72 characters in subject line.
    - Body explains *why*, not what. Reference issue numbers: `Closes #142`.
    - Breaking changes: add `!` after type or `BREAKING CHANGE:` in footer.
    
    Examples:
    ```
    feat(auth): add JWT refresh token rotation
    fix(api): return 403 instead of 500 on missing permission
    chore(deps): upgrade bcrypt to 5.1.1
    refactor(user): extract password validation into domain service
    feat!: remove legacy v1 API endpoints
    
    BREAKING CHANGE: /api/v1/* routes no longer exist. Use /api/v2/*.
    ```
    
    ---
    
    ## Pull requests
    
    ### Before opening a PR
    - Self-review your own diff first. Read every line.
    - All tests pass locally.
    - No debug code, no commented-out blocks, no TODOs without a linked issue.
    - Branch is up to date with the target branch.
    
    ### PR description template
    ```
    ## What
    Short description of what changed and why.
    
    ## How
    Key implementation decisions or tradeoffs worth explaining.
    
    ## Testing
    How was this tested? What scenarios were covered?
    
    ## Checklist
    - [ ] Tests added/updated
    - [ ] Docs updated if needed
    - [ ] No secrets or debug code
    - [ ] Self-reviewed
    ```
    
    ### PR size rules
    - Max ~400 lines changed per PR. Larger → split by concern.
    - One PR = one logical change. Reviewers lose focus on large diffs.
    - Draft PRs are fine for early feedback — mark clearly.
    
    ### Review etiquette
    - Reviewers: distinguish blocking issues from suggestions. Use prefixes:
      - `blocking:` — must fix before merge.
      - `nit:` — minor style/preference, non-blocking.
      - `suggestion:` — take it or leave it, explain your thinking.
    - Authors: respond to every comment. "Done" or explain why you disagree.
    - Approve only what you would be comfortable owning in production.
    
    ### Merge strategy
    - Prefer squash merge for feature branches (clean history on main).
    - Prefer merge commit for release branches (preserve history).
    - Never force-push to shared branches.
    
    ---
    
    ## Approval rules
    
    Minimum before merging:
    - At least 1 approval from someone who understands the changed domain.
    - CI passes: tests, linting, security scan.
    - No unresolved blocking comments.
    
    For sensitive changes (auth, payments, data migrations):
    - 2 approvals minimum.
    - Security review if the change touches trust boundaries.
    
    ---
    
    ## Tags & versioning
    
    Follow Semantic Versioning: `MAJOR.MINOR.PATCH`
    - MAJOR: breaking API change.
    - MINOR: new backward-compatible feature.
    - PATCH: backward-compatible bug fix.
    
    Automate version bumps from conventional commit history when possible.
    Tag releases on `main` with signed tags.
    
  • references/languages/go.md3.5 KB887cf346b616upstream ↗
    # Go — language-specific standards
    
    Load this file for any Go project. Apply these rules in addition to
    the core hardshell standards.
    
    ---
    
    ## Code style
    
    Go style is enforced by tooling, not convention.
    
    - gofmt or goimports must run on every save and in CI. No exceptions.
    - golangci-lint for static analysis. Configure in .golangci.yml.
    - Follow standard Go project layout: cmd/, internal/, pkg/, api/.
    - Use internal/ for packages that must not be imported by external code.
    
    ---
    
    ## Error handling — Go's most important convention
    
    ```go
    // ✓ check every error, wrap with context
    user, err := db.GetUser(ctx, userID)
    if err != nil {
        return fmt.Errorf("getting user %s: %w", userID, err)
    }
    
    // ✗ ignored error
    user, _ := db.GetUser(ctx, userID)
    
    // ✗ no context — impossible to trace in production
    if err != nil {
        return err
    }
    ```
    
    Rules:
    - Never ignore errors with _. Every error must be handled.
    - Wrap errors with fmt.Errorf("context: %w", err) to preserve the chain.
    - Use errors.Is() and errors.As() to inspect wrapped errors.
    - Define sentinel errors: var ErrNotFound = errors.New("not found").
    - Panic only for unrecoverable programmer errors (nil pointer on startup config).
      Never panic on user input or runtime errors.
    
    ---
    
    ## Interfaces
    
    - Define interfaces at the point of use (consumer side), not the provider.
    - Keep interfaces small. io.Reader (1 method) is the ideal.
    - Accept interfaces, return concrete types.
    - Do not define an interface until you have two implementations or a testing need.
    
    ---
    
    ## Concurrency
    
    ```go
    // ✓ always pass context for cancellation
    func (s *Service) FetchData(ctx context.Context, id string) (*Data, error) {
        return s.repo.Get(ctx, id)
    }
    
    // ✓ errgroup for concurrent work with error propagation
    g, ctx := errgroup.WithContext(ctx)
    g.Go(func() error { return fetchUsers(ctx) })
    g.Go(func() error { return fetchOrders(ctx) })
    if err := g.Wait(); err != nil {
        return fmt.Errorf("concurrent fetch: %w", err)
    }
    ```
    
    Rules:
    - Pass context.Context as the first argument to every function that does I/O.
    - Never store context in a struct — pass it explicitly.
    - Channels for communication. Mutexes for shared state. Not both for the same thing.
    - Always close channels from the sender side, never the receiver.
    - Run tests with race detector in CI: go test -race ./...
    
    ---
    
    ## Testing — table-driven pattern
    
    ```go
    func TestCalculateDiscount(t *testing.T) {
        tests := []struct {
            name     string
            price    float64
            rate     float64
            expected float64
            wantErr  bool
        }{
            {"valid discount", 100.0, 0.2, 80.0, false},
            {"zero rate",      100.0, 0.0, 100.0, false},
            {"invalid rate",   100.0, 1.5, 0.0,   true},
        }
        for _, tt := range tests {
            t.Run(tt.name, func(t *testing.T) {
                got, err := CalculateDiscount(tt.price, tt.rate)
                if (err != nil) != tt.wantErr {
                    t.Errorf("unexpected error: %v", err)
                }
                if got != tt.expected {
                    t.Errorf("got %v, want %v", got, tt.expected)
                }
            })
        }
    }
    ```
    
    Use table-driven tests for all functions with multiple scenarios.
    
    ---
    
    ## Tooling — standard Go stack
    
    | Purpose        | Tool          |
    |----------------|---------------|
    | Formatter      | gofmt/goimports|
    | Linter         | golangci-lint |
    | Race detector  | go test -race |
    | Security audit | govulncheck   |
    | Build/release  | goreleaser    |
    
    go vet must pass with zero warnings.
    govulncheck in CI to detect known CVEs in dependencies.
    
  • references/languages/python.md5.7 KB06f62fee7461upstream ↗
    # Python standards
    
    Load this file when the project uses Python.
    
    ---
    
    ## Style — PEP 8 (always enforced)
    
    - Indentation: 4 spaces. Never tabs.
    - Max line length: 88 characters (Black default). Configure your linter to match.
    - Two blank lines between top-level definitions (functions, classes).
    - One blank line between methods inside a class.
    - Imports: standard library → third-party → local, separated by blank lines.
    - No wildcard imports (`from module import *`).
    - Snake_case for variables, functions, modules. PascalCase for classes. UPPER_CASE for constants.
    
    Run `black` for formatting and `ruff` or `flake8` for linting.
    These are non-negotiable in any Python project.
    
    ---
    
    ## Type hints (required for all new code)
    
    Type hints are not optional. They are documentation that the interpreter can check.
    
    ```python
    # Wrong
    def get_user(user_id):
        ...
    
    # Right
    from typing import Optional
    
    def get_user(user_id: int) -> Optional[User]:
        ...
    ```
    
    Rules:
    - Annotate all function parameters and return types.
    - Use `Optional[X]` (or `X | None` in Python 3.10+) for nullable values.
    - Use `list[str]`, `dict[str, int]` (lowercase, Python 3.9+) not `List`, `Dict`.
    - Use `TypedDict` or dataclasses for structured dicts.
    - Run `mypy` or `pyright` in CI. Type errors are bugs.
    
    ---
    
    ## Docstrings (required for public API)
    
    Use Google-style docstrings for all public functions, classes, and modules.
    
    ```python
    def calculate_discount(price: float, rate: float) -> float:
        """Calculate the discounted price.
    
        Args:
            price: The original price in euros.
            rate: The discount rate as a decimal (0.0 to 1.0).
    
        Returns:
            The final price after applying the discount.
    
        Raises:
            ValueError: If rate is not between 0.0 and 1.0.
        """
        if not 0.0 <= rate <= 1.0:
            raise ValueError(f"Discount rate must be 0.0–1.0, got {rate}")
        return price * (1 - rate)
    ```
    
    Private methods (prefixed with `_`) do not require docstrings unless complex.
    All public methods, classes, and modules do.
    
    ---
    
    ## Pythonic patterns — prefer these
    
    ```python
    # Use list comprehensions instead of loops for simple transforms
    squares = [x ** 2 for x in range(10)]  # not: squares = []; for x in ...: squares.append(...)
    
    # Use enumerate instead of range(len(...))
    for i, item in enumerate(items):  # not: for i in range(len(items)):
    
    # Use dict.get() for safe access
    value = config.get("timeout", 30)  # not: value = config["timeout"] if "timeout" in config else 30
    
    # Use context managers for resource management
    with open("file.txt") as f:  # not: f = open(...); try: ... finally: f.close()
        content = f.read()
    
    # Use dataclasses for data containers
    from dataclasses import dataclass
    
    @dataclass
    class Order:
        id: int
        total: float
        status: str = "pending"
    
    # Use f-strings for formatting
    message = f"User {user.name} logged in"  # not: "User %s logged in" % user.name
    
    # Use pathlib instead of os.path
    from pathlib import Path
    config_path = Path("config") / "settings.json"  # not: os.path.join("config", "settings.json")
    ```
    
    ---
    
    ## Error handling
    
    ```python
    # Use specific exceptions, never bare except
    try:
        result = risky_operation()
    except ValueError as e:
        logger.error("Invalid value: %s", e)
        raise
    
    # Never do this
    try:
        ...
    except:  # catches SystemExit, KeyboardInterrupt — always wrong
        pass
    
    # Custom domain exceptions
    class PaymentError(Exception):
        """Base class for payment domain errors."""
    
    class InsufficientFundsError(PaymentError):
        def __init__(self, required: float, available: float):
            self.required = required
            self.available = available
            super().__init__(f"Need {required}, only {available} available")
    ```
    
    ---
    
    ## Dependency & environment management
    
    - Use `pyproject.toml` (PEP 517/518). Avoid `setup.py` for new projects.
    - Pin all dependencies in `requirements.txt` or lock files (`poetry.lock`, `uv.lock`).
    - Use virtual environments. Never install into the system Python.
    - Preferred toolchain: `uv` (fast) or `poetry` (feature-rich). Avoid bare `pip` for projects.
    - Audit dependencies: `pip-audit` or `safety check`.
    - Separate dev dependencies from production dependencies.
    
    ---
    
    ## Security — Python specifics
    
    - Never use `pickle` to deserialize untrusted data. It executes arbitrary code.
    - Never use `eval()` or `exec()` on user input.
    - Use `subprocess` with a list of arguments, never a shell string:
      ```python
      # Wrong — shell injection possible
      subprocess.run(f"convert {filename}", shell=True)
    
      # Right
      subprocess.run(["convert", filename], check=True)
      ```
    - Use `secrets` module for cryptographic tokens, not `random`.
    - Use `hashlib` with proper algorithms. Never `md5` or `sha1` for security.
    
    ---
    
    ## Testing (Python)
    
    Preferred framework: `pytest`.
    
    ```python
    # Test file naming: test_<module>.py or <module>_test.py
    # Test function naming: test_<what>_<condition>_<expected>
    
    def test_calculate_discount_with_fifty_percent_returns_half_price():
        result = calculate_discount(price=100.0, rate=0.5)
        assert result == 50.0
    
    def test_calculate_discount_with_invalid_rate_raises_value_error():
        with pytest.raises(ValueError, match="Discount rate must be"):
            calculate_discount(price=100.0, rate=1.5)
    ```
    
    Use `pytest-cov` for coverage. Use `pytest-mock` or `unittest.mock` for mocking.
    Use `freezegun` for time-dependent tests.
    Use `factory_boy` or fixtures for test data — never hardcode magic values.
    
    ---
    
    ## Toolchain summary
    
    | Purpose | Tool |
    |---------|------|
    | Formatter | `black` |
    | Linter | `ruff` (replaces flake8 + isort + pyupgrade) |
    | Type checker | `mypy` or `pyright` |
    | Test runner | `pytest` |
    | Coverage | `pytest-cov` |
    | Security audit | `pip-audit` |
    | Package manager | `uv` or `poetry` |
    
    Configure all tools in `pyproject.toml`. Run them all in CI before merge.
    
  • references/languages/typescript.md4.0 KBa35d10a65f2bupstream ↗
    # TypeScript / JavaScript standards
    
    Load this file when the project uses TypeScript or JavaScript.
    Prefer TypeScript for all new projects. JavaScript without types is legacy.
    
    ---
    
    ## TypeScript — always prefer it over plain JavaScript
    
    New projects: TypeScript only. No exceptions.
    Existing JS projects: migrate incrementally, starting with the most critical modules.
    
    ### tsconfig.json — strict mode is mandatory
    
    ```json
    {
      "compilerOptions": {
        "strict": true,
        "noUncheckedIndexedAccess": true,
        "exactOptionalPropertyTypes": true,
        "noImplicitReturns": true,
        "noFallthroughCasesInSwitch": true
      }
    }
    ```
    
    `strict: true` enables: noImplicitAny, strictNullChecks, strictFunctionTypes,
    and others. Every one catches real bugs. Never disable them.
    
    ---
    
    ## Types
    
    ```typescript
    // ✓ explicit, narrow types
    function getUser(id: string): Promise<User | null> { ... }
    
    // ✗ any defeats the purpose of TypeScript
    function process(data: any): any { ... }
    
    // ✓ unknown is the safe alternative when type is truly unknown
    function parsePayload(raw: unknown): ParsedData {
      if (!isValidPayload(raw)) throw new ValidationError("Invalid payload");
      return raw as ParsedData;
    }
    ```
    
    Rules:
    - `any` is forbidden except in test utilities and migration shims. Use `unknown`.
    - `as` type assertions require a comment explaining why it is safe.
    - Prefer `interface` for object shapes that will be extended.
      Prefer `type` for unions, intersections, and computed types.
    - Use `readonly` on properties that must not be mutated after construction.
    - `enum` creates runtime overhead. Prefer `const` object maps or string literal unions.
    
    ---
    
    ## Null handling
    
    - Enable `strictNullChecks`. It is part of `strict: true`.
    - Treat `null` and `undefined` as different things.
      `null` = intentionally absent. `undefined` = not yet set.
    - Optional chaining (?.) and nullish coalescing (??) are fine — but verify
      the fallback value is semantically correct, not just "makes the error go away."
    
    ---
    
    ## Async / await
    
    ```typescript
    // ✓ always await, always handle errors
    async function fetchUser(id: string): Promise<User> {
      try {
        const response = await api.get(`/users/${id}`);
        return response.data;
      } catch (error) {
        logger.error("Failed to fetch user", { id, error });
        throw new UserNotFoundError(id);
      }
    }
    
    // ✗ floating promise — error is silently swallowed
    fetchUser(id);
    ```
    
    - Never use floating promises. Either await or chain .catch().
    - Promise.all() for concurrent independent async operations.
    - Promise.allSettled() when you need all results regardless of individual failures.
    - Never mix async/await and raw .then() in the same function.
    
    ---
    
    ## Tooling — standard TS/JS stack
    
    | Purpose         | Tool                         |
    |-----------------|------------------------------|
    | Runtime types   | zod or valibot               |
    | Linter          | ESLint with typescript-eslint|
    | Formatter       | Prettier                     |
    | Test runner     | Vitest (or Jest)             |
    | Build           | tsc, esbuild, or tsup        |
    | Security audit  | npm audit / pnpm audit       |
    | Package manager | pnpm (preferred) or npm      |
    
    Configure ESLint and Prettier in eslint.config.js and .prettierrc.
    Both must run in CI. PRs with lint errors are not mergeable.
    
    ---
    
    ## Error handling
    
    ```typescript
    // ✓ typed custom errors
    class PaymentError extends Error {
      constructor(
        message: string,
        public readonly code: string,
        public readonly transactionId: string
      ) {
        super(message);
        this.name = "PaymentError";
      }
    }
    
    // ✓ type narrowing in catch
    try {
      await processPayment(order);
    } catch (error) {
      if (error instanceof PaymentError) {
        logger.warn("Payment declined", { code: error.code });
        return { success: false, reason: error.code };
      }
      throw error; // re-throw unexpected errors
    }
    ```
    
    - `catch (error)` gives you `unknown` in strict mode — narrow the type before using it.
    - Create typed error classes for domain errors.
    - Never surface error.message directly to the user — it may expose internals.
    
  • references/performance.md4.5 KB1e4c023e305dupstream ↗
    # Performance standards
    
    Load this file when the task involves performance, optimization, scaling, or complexity analysis.
    
    ---
    
    ## Measure before optimizing
    
    Never optimize code you haven't measured.
    Premature optimization is the most common source of complex, unmaintainable code.
    
    Before touching performance:
    1. Define what "slow" means. Set a concrete target (e.g., "p95 < 200ms").
    2. Profile. Find the actual bottleneck — it is almost never where you think.
    3. Fix the bottleneck. Ignore everything else.
    4. Measure again. Confirm the improvement.
    
    ---
    
    ## Algorithmic complexity — know your costs
    
    Always reason about complexity before writing loops inside loops.
    
    | Operation | Complexity | Comment |
    |-----------|-----------|---------|
    | Hash lookup | O(1) | Use dicts/maps for frequent lookups |
    | Array access by index | O(1) | |
    | Binary search | O(log n) | Requires sorted data |
    | Single loop | O(n) | Acceptable for most cases |
    | Nested loops | O(n²) | Alarm bell for n > 1000 |
    | Sorting | O(n log n) | Standard sort algorithms |
    | Recursive without memoization | O(2ⁿ) or worse | Almost always wrong |
    
    Rules:
    - O(n²) is acceptable only for n < ~1000 and non-hot paths.
    - If the data set can grow unboundedly, O(n²) is a bug waiting to happen.
    - When in doubt, write it simply first. Optimize only after profiling.
    
    ---
    
    ## Database performance
    
    N+1 queries are the most common performance killer in web applications.
    
    Detecting N+1:
    ```
    # This runs 1 query to get orders, then 1 query per order to get user → N+1
    for order in get_all_orders():
        print(order.user.name)  # lazy load triggers a query each time
    
    # This runs 1 query with a JOIN
    orders = get_all_orders_with_users()
    for order in orders:
        print(order.user.name)
    ```
    
    Rules:
    - Use eager loading / joins when fetching related data in a loop.
    - Index columns used in WHERE, JOIN, and ORDER BY clauses.
    - Use LIMIT/pagination — never return unbounded result sets.
    - Avoid SELECT * in production queries — specify columns.
    - Use query explain/analyze to understand execution plans for slow queries.
    - Use connection pooling. Never open a new DB connection per request.
    
    ---
    
    ## Caching
    
    Cache when: data is expensive to compute, read far more often than written,
    and tolerable staleness exists.
    
    Do not cache when: data must always be fresh, or the cache adds more complexity than it saves.
    
    Cache hierarchy (fastest to slowest):
    ```
    In-process memory (dict/map)  →  nanoseconds, lost on restart
    Distributed cache (Redis)     →  microseconds, shared across instances
    CDN / HTTP cache              →  milliseconds, for static/semi-static content
    Database query cache          →  use sparingly, easy to misuse
    ```
    
    Cache invalidation rules:
    - Set explicit TTLs. Never cache forever without a TTL.
    - Invalidate on write, not on read.
    - Cache the result, not the computation. Cache at the highest useful level.
    - Monitor cache hit rates. A low hit rate means the cache is not helping.
    
    ---
    
    ## I/O and concurrency
    
    I/O (network, disk, database) is orders of magnitude slower than CPU.
    
    Rules:
    - Batch I/O operations where possible. 1 query for 100 records beats 100 queries for 1 record.
    - Use async/non-blocking I/O for I/O-bound work (HTTP calls, file reads).
    - Use worker pools/queues for CPU-bound work.
    - Never block the main thread/event loop with synchronous I/O.
    - Set timeouts on all external calls. An unconfigured timeout is a guaranteed outage.
    - Handle backpressure — don't queue unbounded work.
    
    ---
    
    ## Memory
    
    - Release resources explicitly: close files, connections, cursors.
    - Use streaming / pagination for large data sets. Never load millions of records into memory.
    - Watch for reference cycles in long-lived objects.
    - Profile memory usage under realistic load, not just CPU.
    
    ---
    
    ## Frontend performance (when applicable)
    
    - Minimize bundle size. Audit and remove unused dependencies.
    - Lazy-load code that is not needed on initial render.
    - Images: use modern formats (WebP/AVIF), correct dimensions, lazy loading.
    - Avoid layout thrashing: batch DOM reads before DOM writes.
    - Debounce/throttle event handlers (scroll, resize, input).
    - Use browser caching headers correctly (Cache-Control, ETag).
    
    ---
    
    ## Performance review checklist
    
    Before calling a task complete, check:
    - Are there any loops that query a database or make network calls?
    - Are result sets bounded by LIMIT or pagination?
    - Are indexes in place for the query patterns being used?
    - Are external calls covered by timeouts?
    - Is there any synchronous blocking I/O on a hot path?
    
  • references/skill-development.md4.3 KB5b7798acd505upstream ↗
    # Skill Development Standards
    
    Load this file when creating, modifying, or reviewing agent skills.
    
    ---
    
    ## Core principle
    
    A skill is code. Treat it like production code.
    
    Before using a skill, verify it works. Before committing changes, validate everything.
    
    ---
    
    ## Skill validation checklist
    
    ### Before first use (load time)
    
    1. **Read SKILL.md** - Understand what the skill claims to do
    2. **Check validation script** - If `validation:` field exists, run it
    3. **Test basic commands** - At least one smoke test per module
    
    Example validation in SKILL.md:
    ```yaml
    ---
    name: my-skill
    version: 1.0.0
    validation: scripts/validate.sh
    ---
    ```
    
    ### Before committing changes
    
    1. **Run validation script** - `bash scripts/validate.sh` or equivalent
    2. **Test all documented commands** - Every example in SKILL.md must work
    3. **Check documentation sync** - SKILL.md examples match actual CLI
    
    ---
    
    ## Documentation accuracy
    
    ### SKILL.md must match reality
    
    Every command example in SKILL.md must be verified to work:
    
    ```
    ❌ Wrong: Documentation says "imm-romania mail list" but CLI uses "mail read"
    ✅ Right: Documentation matches actual CLI commands
    ```
    
    When you change CLI commands:
    1. Update SKILL.md immediately
    2. Update help text in CLI
    3. Test the example commands
    
    ### Keep examples minimal and working
    
    ```bash
    # Good: minimal, verifiable
    imm-romania mail connect
    
    # Bad: requires setup user doesn't have
    imm-romania mail send --to "[email protected]" ...
    ```
    
    ---
    
    ## Validation script requirements
    
    Every skill with CLI commands should have a validation script:
    
    ```bash
    #!/bin/bash
    # scripts/validate.sh - Test basic functionality
    
    set -e
    
    echo "Testing module X..."
    python3 scripts/cli.py module command --arg value
    
    echo "Testing module Y..."
    python3 scripts/cli.py module command
    
    echo "✅ All tests passed"
    ```
    
    Requirements:
    - Exit code 0 on success, non-zero on failure
    - Test all core commands (at least one per module)
    - Be idempotent (can run multiple times safely)
    - Not require user-specific data (use test fixtures)
    
    ---
    
    ## Common mistakes to avoid
    
    ### Mistake 1: Assuming without verifying
    
    ```
    ❌ "The skill lists files, so files list must work"
    ✅ Run the command. Check the output. Verify it matches expectations.
    ```
    
    ### Mistake 2: Documentation drift
    
    ```
    ❌ SKILL.md says "command X" but code has "command Y"
    ✅ After every code change, verify SKILL.md examples
    ```
    
    ### Mistake 3: No validation script
    
    ```
    ❌ Skill has no automated testing
    ✅ Add scripts/validate.sh and reference it in SKILL.md
    ```
    
    ### Mistake 4: Testing happy path only
    
    ```
    ❌ Validation only tests "it runs"
    ✅ Validation tests actual output (files listed, email sent, etc.)
    ```
    
    ---
    
    ## When reviewing a skill
    
    Run this mental checklist:
    
    - [ ] SKILL.md describes actual functionality
    - [ ] All command examples work as documented
    - [ ] Validation script exists and passes
    - [ ] Error handling exists (not just happy path)
    - [ ] Dependencies are documented
    - [ ] Setup instructions are complete and tested
    
    ---
    
    ## Fixing a broken skill
    
    When you find a skill that doesn't work:
    
    1. **Document the problem** - Create VERIFICATION.md with what's broken
    2. **Fix the root cause** - Don't patch symptoms
    3. **Add validation** - Ensure it won't regress
    4. **Update documentation** - Sync SKILL.md with reality
    5. **Commit everything together** - Fix + validation + docs in one commit
    
    ---
    
    ## Agent behavior for skills
    
    When loading or using a skill:
    
    1. Read SKILL.md first (it's the contract)
    2. If `validation:` field exists, run it before using the skill
    3. If no validation script, do a basic smoke test
    4. If something doesn't work as documented, fix it before proceeding
    5. Never assume a skill works without verification
    
    ---
    
    ## Example: Fixing a broken command
    
    Problem: `files list` returns data but doesn't print it
    
    ```python
    # Before (broken)
    if command == 'list':
        path = command_args[0] if command_args else '/'
        client.list(path)  # Returns data, doesn't print
    ```
    
    ```python
    # After (fixed)
    if command == 'list':
        path = command_args[0] if command_args else '/'
        results = client.list(path)
        if results:
            from modules.nextcloud.nextcloud import print_list
            print_list(results)
        else:
            print("(empty)")
    ```
    
    Lesson: Always verify that output is displayed, not just returned.
  • references/testing.md3.7 KB84f9b01d1152upstream ↗
    # Testing standards
    
    Load this file when the task involves writing, fixing, or reviewing tests.
    
    ---
    
    ## Core philosophy
    
    Tests are not optional. They are the proof that code works.
    A test that only checks "it ran without crashing" is worse than no test — it gives false confidence.
    
    Test behavior, not implementation. If you can refactor the internals without touching tests, the tests are correct.
    
    ---
    
    ## TDD loop (use for new features)
    
    ```
    1. Write a failing test that describes the desired behavior.
    2. Write the minimum code to make it pass.
    3. Refactor — clean the code without breaking the test.
    4. Repeat.
    ```
    
    Do not skip step 1. Writing the test first forces you to think about the interface before the implementation.
    
    ---
    
    ## Test pyramid
    
    ```
             /\
            /  \   E2E tests (few, slow, test full flows)
           /----\
          /      \  Integration tests (moderate, test component boundaries)
         /--------\
        /          \ Unit tests (many, fast, test single functions/classes)
       /------------\
    ```
    
    - Unit tests: the foundation. Fast, isolated, no I/O, no network.
    - Integration tests: test that layers work together (service + repo + DB).
    - E2E tests: test critical user journeys only. Keep them minimal.
    
    Aim for: ~70% unit, ~20% integration, ~10% E2E.
    
    ---
    
    ## What every test must have
    
    Structure: Arrange → Act → Assert (AAA pattern)
    
    ```
    # Arrange: set up the input and dependencies
    user = User(email="[email protected]", role="admin")
    repo = FakeUserRepository([user])
    service = UserService(repo)
    
    # Act: call the thing being tested
    result = service.get_by_email("[email protected]")
    
    # Assert: verify the outcome
    assert result.email == "[email protected]"
    assert result.role == "admin"
    ```
    
    One assertion per concept (not per line — per logical idea).
    Test name must describe: what is being tested, under what condition, what the expected result is.
    
    Good: `test_login_returns_403_when_password_is_wrong`
    Bad: `test_login_2` or `test_it_works`
    
    ---
    
    ## What to test
    
    For every function/method, cover:
    - Happy path: valid input, expected output.
    - Edge cases: empty string, null, zero, negative, max value.
    - Error paths: invalid input, missing resource, permission denied.
    - Boundary conditions: off-by-one, first/last element.
    
    For every API endpoint, cover:
    - Success response (correct status code + body shape).
    - Auth failure (401, 403).
    - Validation failure (400 with meaningful error).
    - Not found (404).
    
    ---
    
    ## Test isolation rules
    
    - Unit tests must not touch the filesystem, network, or database.
    - Use fakes/stubs/mocks for external dependencies.
    - Prefer fakes (simple in-memory implementations) over mocks (behavior verification).
    - Use mocks only when you need to assert that a specific call was made.
    - Each test must be independent — no shared mutable state between tests.
    - Tests must pass in any order.
    
    ---
    
    ## Coverage
    
    Coverage is a floor, not a goal.
    - Minimum: 70% line coverage on business logic.
    - 100% coverage does not mean the code is correct. It means every line ran.
    - Untested critical paths (auth, payments, data writes) are always a blocker.
    - Do not write tests just to increase coverage numbers.
    
    ---
    
    ## Test code quality
    
    Test code is production code. Apply the same standards:
    - No magic numbers in assertions — use named constants.
    - No copy-paste between tests — extract helpers.
    - Keep setup minimal. A test that needs 50 lines of setup is testing too much.
    - If a test is hard to write, the production code is probably too coupled.
    
    ---
    
    ## Regression tests
    
    Every bug fix must include a regression test:
    1. Write a test that reproduces the bug (it fails).
    2. Fix the bug.
    3. Confirm the test passes.
    4. The test lives permanently — it documents the bug and prevents recurrence.
    
  • .github/ISSUE_TEMPLATE/bug_report.md622 B1f7b04e3083fupstream ↗
    ---
    name: bug report
    about: Report a bug in Hardshell coding standards
    title: '[BUG] '
    labels: bug
    assignees: ''
    ---
    
    ## Description
    A clear and concise description of what the bug is.
    
    ## Steps to Reproduce
    1. Go to '...'
    2. Click on '....'
    3. Scroll down to '....'
    4. See error
    
    ## Expected Behavior
    A clear and concise description of what you expected to happen.
    
    ## Actual Behavior
    A clear and concise description of what actually happened.
    
    ## Environment
    - OpenClaw version: [e.g. 1.0.0]
    - Hardshell version: [e.g. 3.0.0]
    - OS: [e.g. Ubuntu 22.04]
    
    ## Additional Context
    Add any other context about the problem here.
  • .github/ISSUE_TEMPLATE/feature_request.md543 Bbf0252d4ed8bupstream ↗
    ---
    name: feature request
    about: Suggest an improvement to Hardshell coding standards
    title: '[FEATURE] '
    labels: enhancement
    assignees: ''
    ---
    
    ## Is your feature request related to a problem?
    A clear and concise description of what the problem is.
    
    ## Proposed Solution
    A clear and concise description of what you want to happen.
    
    ## Alternatives Considered
    A clear and concise description of any alternative solutions or features you've considered.
    
    ## Additional Context
    Add any other context or screenshots about the feature request here.
  • .github/PULL_REQUEST_TEMPLATE.md789 B79bb100020bbupstream ↗
    # Pull Request Template
    
    ## Description
    A clear and concise description of the changes.
    
    ## Type of Change
    - [ ] Bug fix (non-breaking change that fixes an issue)
    - [ ] New feature (non-breaking change that adds functionality)
    - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
    - [ ] Documentation update
    
    ## Checklist
    - [ ] I have followed the Hardshell coding standards
    - [ ] I have performed a self-review of my code
    - [ ] I have commented my code, particularly in hard-to-understand areas
    - [ ] I have made corresponding changes to the documentation
    - [ ] My changes generate no new warnings
    
    ## Testing
    Describe the tests that you ran to verify your changes.
    
    ## Additional Context
    Add any other context about the pull request here.
  • .gitignore59 B45f2dd7c5906upstream ↗
    # Claude Desktop artifacts (not used by OpenClaw)
    .claude/
    
  • CHANGELOG.md2.5 KB4d11e48e53ddupstream ↗
    # Changelog
    
    All notable changes to this project will be documented in this file.
    
    The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
    and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
    
    ## [3.2.0] - 2026-05-16
    
    ### Added
    
    - **Agent behavior reference** (`references/agent-behavior.md`) with four principles derived from [Andrej Karpathy's observations on LLM coding pitfalls](https://x.com/karpathy/status/2015883857489522876):
      1. **Think Before Coding** — surface assumptions, present multiple interpretations, push back when warranted
      2. **Simplicity First** — minimum code that solves the problem, nothing speculative
      3. **Surgical Changes** — touch only what you must, match existing style, don't refactor adjacent code
      4. **Goal-Driven Execution** — transform imperative tasks into verifiable goals with explicit success criteria
    - Updated `README.md` with agent behavior section and acknowledgments
    - Created this `CHANGELOG.md`
    
    ### Changed
    
    - `SKILL.md` §5 — added reference to `references/agent-behavior.md` for editing existing code or ambiguous requests
    - `scripts/validate.sh` — expanded reference file list from 7 to 8 files
    
    ## [3.1.0] - 2026-04-27
    
    ### Added
    
    - Validation script (`scripts/validate.sh`) for smoke-testing the skill
    - `.gitignore` for `.claude/` directory
    - `references/skill-development.md` — standards for creating and validating OpenClaw skills
    
    ## [3.0.0] - 2026-04-23
    
    ### Added
    
    - Initial release of Hardshell coding standards skill
    - Security rules (input validation, secrets, auth, common vulnerabilities, API security, dependencies)
    - Architecture & design principles (SOLID, layered architecture, design patterns, database)
    - Clean code guidelines (naming, functions, variables, error handling, comments, style)
    - Review checklist (correctness, security, architecture, clean code, tests)
    - Agent behavior rules (flag prefixes, skill loading contract)
    - Reference files: `git-workflow.md`, `performance.md`, `testing.md`
    - Language-specific references: `python.md`, `typescript.md`, `go.md`
    
    ## [1.0.0] - 2026-01-20
    
    ### Added
    
    - Initial proof-of-concept release
    
    [3.2.0]: https://github.com/asistent-alex/openclaw-hardshell/compare/v3.1.0...v3.2.0
    [3.1.0]: https://github.com/asistent-alex/openclaw-hardshell/compare/v3.0.0...v3.1.0
    [3.0.0]: https://github.com/asistent-alex/openclaw-hardshell/compare/v1.0.0...v3.0.0
    [1.0.0]: https://github.com/asistent-alex/openclaw-hardshell/releases/tag/v1.0.0
    
  • LICENSE1.0 KB165261b50806upstream ↗
    MIT License
    
    Copyright (c) 2026 OpenClaw Community
    
    Permission is hereby granted, free of charge, to any person obtaining a copy
    of this software and associated documentation files (the "Software"), to deal
    in the Software without restriction, including without limitation the rights
    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    copies of the Software, and to permit persons to whom the Software is
    furnished to do so, subject to the following conditions:
    
    The above copyright notice and this permission notice shall be included in all
    copies or substantial portions of the Software.
    
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
    SOFTWARE.

Plain-text copy, no login: /skill-bundles/asistent-alex-openclaw-hardshell.md

// REPO STATS

1 stars
0 open issues
Last commit: 6mo ago