buildpad-steering Skill

Establish the backend first. A Buildpad project's backend is either the Buildpad Engine or Supabase, and some parts of this file hold for one of them only. Before you act on anything in this file, find the backend with these steps, in order, and stop at the first step that answers:

1. Read .buildpad/project.json at the project root. If it is JSON and its field backend is "engine" or "supabase", that is the backend. If .buildpad/backend-answer.json names the other backend, tell the developer the two files disagree, and follow .buildpad/project.json.
2. Otherwise read .buildpad/backend-answer.json in the same way; if its backend is "engine" or "supabase", that is the backend.
3. If a folder named supabase at the project root holds a file named config.toml, or holds a folder named migrations that holds a file whose name ends in .sql, the backend is Supabase.
4. Otherwise ask the developer once: "Is this project's backend the Buildpad Engine or Supabase?" Write the answer to .buildpad/backend-answer.json as {"buildpadBackendAnswer": 1, "backend": "engine"} or {"buildpadBackendAnswer": 1, "backend": "supabase"}, and ask the developer to commit that file. Do not add it to .gitignore. Never write .buildpad/project.json.

To find the backend, do not open an environment file (.env, .env.*) or an MCP configuration file, and do not call a tool that returns project credentials.

Then follow only the parts for that backend. A part starts at a line that holds only a comment whose text is buildpad + -backend: engine or buildpad + -backend: supabase, and ends at the next line that holds only a comment whose text is /buildpad + -backend. A comment that merely mentions a backend is not a part. A file whose first line, after any front matter, holds only a comment whose text is buildpad + -backend-file: engine (or supabase) holds for that backend only, and so does every file in a folder named engine-only or supabase-only. Skip the other backend's parts and copy no code from them; everything else holds for both. On an Engine project, when this file says that something is not available, tell the developer so and stop: do not build a substitute.

Role

You are a specialized skill for maintaining .kiro/steering/ as persistent project memory.

Core Mission

Role: Maintain .kiro/steering/ as persistent project memory.

Mission:

• Bootstrap: Generate core steering from codebase (first-time)
• Sync: Keep steering and codebase aligned (maintenance)
• Preserve: User customizations are sacred, updates are additive

Success Criteria:

• Steering captures patterns and principles, not exhaustive lists
• Code drift detected and reported
• All .kiro/steering/*.md treated equally (core + custom)

Execution Steps

Step 1: Gather Context

If steering context is already available from conversation, skip redundant file reads.

• For Bootstrap mode: Read templates from .kiro/settings/templates/steering/ (if that directory does not exist, first copy this skill's bundled settings-templates/steering/ directory to .kiro/settings/templates/steering/)
• For Sync mode: Read all existing .kiro/steering/*.md files
• Read rules/steering-principles.md from this skill's directory for steering principles

Scenario Detection

Check .kiro/steering/ status:

Bootstrap Mode: Empty OR missing core files (product.md, tech.md, structure.md) Sync Mode: All core files exist

Bootstrap Flow

1. Load templates from .kiro/settings/templates/steering/
2. Analyze codebase (JIT):

Parallel Research

The following research areas are independent and can be executed in parallel:

1. Product analysis: README, package.json, documentation files for purpose, value, core capabilities
2. Tech analysis: Config files, dependencies, frameworks for technology patterns and decisions. For the backend, record in the tech steering the backend that "Establish the backend first" above established: the Buildpad Engine or Supabase. Never infer the backend from dependency or variable names: an Engine project also carries @supabase/* packages and NEXT_PUBLIC_SUPABASE_* variables, because it keeps the Supabase client for sign-in.
3. Structure analysis: Directory tree, naming conventions, import patterns for organization

After all parallel research completes, synthesize patterns for steering files.

3. Extract patterns (not lists):
   • Product: Purpose, value, core capabilities
   • Tech: Frameworks, decisions, conventions
   • Structure: Organization, naming, imports
4. Generate steering files (follow templates)
5. Load principles from rules/steering-principles.md from this skill's directory
6. Present summary for review

Focus: Patterns that guide decisions, not catalogs of files/dependencies.

Sync Flow

1. Load all existing steering (.kiro/steering/*.md)
2. Analyze codebase for changes (JIT)
3. Detect drift:
   • Steering → Code: Missing elements → Warning
   • Code → Steering: New patterns → Update candidate
   • Custom files: Check relevance
4. Propose updates (additive, preserve user content)
5. Report: Updates, warnings, recommendations

Update Philosophy: Add, don't replace. Preserve user sections.

Granularity Principle

From rules/steering-principles.md (in this skill's directory):

"If new code follows existing patterns, steering shouldn't need updating."

Document patterns and principles, not exhaustive lists.

Bad: List every file in directory tree Good: Describe organization pattern with examples

Tool Guidance

• Glob: Find source/config files
• Read: Read steering, docs, configs
• Grep: Search patterns
• Bash with ls: Analyze structure

JIT Strategy: Fetch when needed, not upfront.

Output Description

Chat summary only (files updated directly).

Bootstrap:

Steering Created

## Generated:
- product.md: [Brief description]
- tech.md: [Key stack]
- structure.md: [Organization]

Review and approve as Source of Truth.

Sync:

Steering Updated

## Changes:
- tech.md: React 18 → 19
- structure.md: Added API pattern

## Code Drift:
- Components not following import conventions

## Recommendations:
- Consider api-standards.md

Examples

Bootstrap

Input: Empty steering, React TypeScript project Output: 3 files with patterns - "Feature-first", "TypeScript strict", "React 19"

Sync

Input: Existing steering, new /api directory Output: Updated structure.md, flagged non-compliant files, suggested api-standards.md

Safety & Fallback

• Security: Never include keys, passwords, secrets (see principles)
• Uncertainty: Report both states, ask user
• Preservation: Add rather than replace when in doubt

Notes

• All .kiro/steering/*.md loaded as project memory
• Templates and principles are external for customization
• Focus on patterns, not catalogs
• "Golden Rule": New code following patterns shouldn't require steering updates
• .kiro/settings/ content should NOT be documented in steering files (settings are metadata, not project knowledge)