Agent Skills: Planning & Ideation
Relevant source files
The following files were used as context for generating this wiki page:
Agent Skills: Planning & Ideation represents the specialized capabilities integrated into nornir-infrahub to enable AI coding assistants to conduct structured development workflows. These skills provide the logic for brainstorming, formalizing requirements through Product Requirement Documents (PRDs), and translating those requirements into actionable GitHub issues.
The system relies on a vendor-neutral source of truth located in the .agents/ directory, ensuring that planning logic remains portable across different AI tools like Claude Code or Codex.
Sources: dev/adr/0001-adopt-canonical-agentic-structure.md:16-25, AGENTS.md:3-6
Agentic Structure and Portability
The project implements the Canonical OpsMill Agentic Structure, which separates agent-executable logic from human-facing documentation. This architecture ensures that all agents share a single set of planning skills, preventing "agentic drift" between different AI assistants.
The Source of Truth
Agent skills are stored in the .agents/skills/ directory. To support specific tools like Claude, the repository uses a committed symlink at .claude/skills that points to the neutral .agents/ directory. This allows tools to access skills without duplicating files.
Sources: dev/adr/0001-adopt-canonical-agentic-structure.md:23-28, AGENTS.md:162-166
This diagram illustrates the relationship between the vendor-neutral source and the tool-specific adapters:
Core Planning Skills
The repository pins seven shared opsmill-dev skills that facilitate the transition from initial ideation to structured execution.
Sources: dev/adr/0001-adopt-canonical-agentic-structure.md:32-34, skills-lock.json:4-46
Ideation and Refinement
| Skill | Purpose | File Path |
|---|---|---|
grilling-ideas | Brainstorming and refining technical concepts. | .agents/skills/grilling-ideas/SKILL.md |
creating-prd | Formalizing technical requirements into a PRD. | .agents/skills/creating-prd/SKILL.md |
creating-issues | Breaking down PRDs into trackable GitHub issues. | .agents/skills/creating-issues/SKILL.md |
Sources: skills-lock.json:11-25, dev/adr/0001-adopt-canonical-agentic-structure.md:32-34
Strategy for Change Management
When an agent initiates a change, it follows a structured planning sequence:
- Grill Idea: Refine the scope of the change.
- Create PRD: Document the architecture, impact, and requirements.
- Generate Issues: Create task-specific issues to track implementation.
- Implementation: Execute work in feature branches targeting
stable.
Sources: dev/adr/0001-adopt-canonical-agentic-structure.md:36-39, dev/guidelines/git-workflow.md:9-12
Workflow Integration
The planning and ideation skills integrate directly with the repository's git and documentation workflows. Agents are instructed to provide durable, human-facing rationale in the dev/ directory, while executable skills remain in .agents/.
Sources: dev/adr/0001-adopt-canonical-agentic-structure.md:36-39, AGENTS.md:8-13
Dependency and Versioning
Skills are version-pinned using content hashes in skills-lock.json. This ensures that planning logic updates are deliberate and verifiable across environments.
Sources: dev/adr/0001-adopt-canonical-agentic-structure.md:32-34, skills-lock.json:1-48
Documentation and Knowledge Mapping
Planning outputs must align with the project's documentation standards. Agents use the Diataxis framework to organize generated content into:
- Guides: Task-oriented how-to pages.
- Topics: Understanding-oriented explanations.
- References: Information-oriented plugin API docs.
Sources: dev/guidelines/documentation.md:12-20, AGENTS.md:127-133
Planning Boundaries
Agents must adhere to specific boundaries during the ideation phase:
- Minimal Changes: Focus on bridging Nornir and Infrahub; reject scope creep.
- Type Safety: Carry type annotations on all public functions.
- Ask First: Agents must request sign-off before changing the public plugin API or altering inventory mapping semantics.
Sources: AGENTS.md:87-105, dev/guidelines/git-workflow.md:73-80
The Agent Skills: Planning & Ideation framework provides the necessary guardrails for AI-driven development. By combining versioned executable skills with a dedicated reference layer in dev/, the project maintains a consistent and transparent roadmap for all contributors, human or AI.