contextia new

contextia new creates a new Contextia artifact from a template. Each artifact is a Markdown file with YAML frontmatter, placed in the correct directory with an auto-generated ID.

Synopsis

contextia new <type> [OPTIONS]

Arguments

Argument	Description
type	Artifact type: spec, task, decision, norm

Options

Option	Short	Description
--title <title>	-t	Title for the artifact (required)
--kind <kind>	-k	Task kind: feature, bug, exploration (tasks only)
--spec <id>	-s	Link to a parent spec (tasks and decisions)
--format <fmt>	-f	Output format: human, json, context
--json	-j	Shorthand for --format json
--help	-h	Show help and exit

ID generation

IDs are auto-generated using the pattern {TYPE}-{SLUG}-{SEQ}:

• SPEC-AUTH-001 — first spec with “auth” in the title
• TASK-012 — twelfth task overall
• DEC-API-003 — third decision related to “api”
• NORM-TEST-001 — first testing norm

The slug is derived from the title. The sequence number increments based on existing artifacts of the same type.

Artifact types

Spec

Creates a behavioral specification in .contextia/system/specs/.

$ contextia new spec --title "User Registration"
Created SPEC-REG-001: .contextia/system/specs/SPEC-REG-001.md

Generated file:

---
id: SPEC-REG-001
title: User Registration
status: draft
paths: []
links: []
created: 2026-03-02
---

# User Registration

## Overview

Describe the behavioral contract here.

## Requirements

-

## Acceptance criteria

-

Task

Creates a work order in .contextia/work/tasks/.

$ contextia new task --title "Implement OAuth login" --kind feature --spec SPEC-AUTH-001
Created TASK-007: .contextia/work/tasks/TASK-007.md

Generated file:

---
id: TASK-007
title: Implement OAuth login
kind: feature
status: created
specs:
  - SPEC-AUTH-001
created: 2026-03-02
---

# Implement OAuth login

## Objective

Describe what this task accomplishes.

## Plan

1.

Decision

Creates an architectural decision record in .contextia/system/rationale/.

$ contextia new decision --title "Use PostgreSQL over SQLite" --spec SPEC-DB-003
Created DEC-DB-004: .contextia/system/rationale/DEC-DB-004.md

Norm

Creates a project norm in .contextia/system/norms/.

$ contextia new norm --title "All API endpoints require authentication"
Created NORM-API-001: .contextia/system/norms/NORM-API-001.md

Generated file:

---
id: NORM-API-001
title: All API endpoints require authentication
scope: "src/api/**"
enforcement: error
---

# All API endpoints require authentication

## Rule

Describe the norm clearly and concisely.

## Rationale

Why this norm exists.

## Exceptions

None.

Examples

Create a spec and immediately edit it:

$ contextia new spec --title "Payment Processing" && $EDITOR .contextia/system/specs/SPEC-PAY-001.md

Create a task in JSON mode for scripting:

$ contextia new task --title "Fix login timeout" --kind bug --json
{
  "id": "TASK-013",
  "type": "task",
  "kind": "bug",
  "path": ".contextia/work/tasks/TASK-013.md",
  "title": "Fix login timeout"
}

Create a decision linked to a spec:

$ contextia new decision --title "JWT over session cookies" --spec SPEC-AUTH-001
Created DEC-AUTH-005: .contextia/system/rationale/DEC-AUTH-005.md

Behavior

• The command fails if .contextia/ does not exist. Run contextia init first.
• The --title option is required for all artifact types.
• The --kind option is only valid for tasks and defaults to feature if omitted.
• Files are never overwritten. If an ID collision occurs (unlikely), the sequence number increments.