feat(backlog): add backlog add for interactive issue creation

CHANGELOG.md

@@ -7,7 +7,31 @@ All notable changes to this project will be documented in this file.
 
 **Important:** Changes need to be documented below this block as this is the header section. Each section should be separated by a horizontal rule. Newer changelog entries need to be added on top of prior ones to keep the history chronological with most recent changes first.
 
+
+---
+
+## [0.36.0] - 2026-02-21
+
+### Added
+
+- Enhanced `specfact backlog add` interactive flow with multiline capture (`::END::` sentinel), acceptance criteria, priority, story points, parent selection, and description format selection (`markdown` or `classic`).
+- New `specfact backlog init-config` command to scaffold `.specfact/backlog-config.yaml` with safe provider defaults.
+- Expanded `specfact backlog map-fields` into a multi-provider setup flow (`ado`, `github`) with guided discovery/validation and canonical config persistence under `.specfact/backlog-config.yaml`.
+- GitHub backlog create flow now supports native sub-issue parent linking and optional issue-type / ProjectV2 Type assignment using configured GraphQL metadata.
+- Centralized retry support for backlog adapter write operations with duplicate-safe behavior for non-idempotent creates/comments.
+
+### Fixed
+
+- Azure DevOps interactive sprint/iteration selection now resolves context from `--project-id` so available iterations are discoverable during `backlog add`.
+- Azure DevOps parent candidate discovery no longer hides valid parents via implicit current-iteration filtering in hierarchy selection flows.
+- GitHub backlog field/type extraction now tolerates non-list labels and dict-shaped `issue_type` payloads (`name`/`title`) for more reliable type inference.
+
+### Changed
+
+- Backlog documentation now reflects the current `specfact backlog` command surface and updated `backlog add` behavior in both guide and command reference docs.
+
 ---
+
 ## [0.35.0] - 2026-02-20
 
 ### Added

docs/guides/agile-scrum-workflows.md

@@ -10,6 +10,62 @@ This guide explains how to use SpecFact CLI for agile/scrum workflows, including
 
 Preferred command paths are `specfact backlog ceremony standup ...` and `specfact backlog ceremony refinement ...`. Legacy `backlog daily`/`backlog refine` remain available for compatibility.
 
+Backlog module command surface:
+
+- `specfact backlog add`
+- `specfact backlog analyze-deps`
+- `specfact backlog trace-impact`
+- `specfact backlog verify-readiness`
+- `specfact backlog diff`
+- `specfact backlog sync`
+- `specfact backlog promote`
+- `specfact backlog generate-release-notes`
+- `specfact backlog delta status|impact|cost-estimate|rollback-analysis`
+
+## Backlog Issue Creation (`backlog add`)
+
+Use `specfact backlog add` to create a backlog item with optional parent hierarchy validation and DoR checks.
+
+```bash
+# Non-interactive creation
+specfact backlog add \
+  --adapter github \
+  --project-id nold-ai/specfact-cli \
+  --template github_projects \
+  --type story \
+  --parent FEAT-123 \
+  --title "Implement X" \
+  --body "Acceptance criteria: ..." \
+  --non-interactive
+
+# Enforce Definition of Ready from .specfact/dor.yaml before create
+specfact backlog add \
+  --adapter github \
+  --project-id nold-ai/specfact-cli \
+  --type story \
+  --title "Implement X" \
+  --body "Acceptance criteria: ..." \
+  --check-dor \
+  --repo-path .
+
+# Interactive ADO flow with sprint/iteration selection and story-quality fields
+specfact backlog add \
+  --adapter ado \
+  --project-id "dominikusnold/Specfact CLI"
+```
+
+Key behavior:
+
+- validates parent exists in current backlog graph before creating
+- validates child-parent type compatibility using `creation_hierarchy` from config/template
+- supports interactive prompts when required fields are missing (unless `--non-interactive`)
+- prompts for ADO sprint/iteration selection and resolves available iterations from `--project-id` context
+- supports multiline body and acceptance criteria capture (default sentinel `::END::`)
+- captures priority and story points for story-like items
+- supports description rendering mode (`markdown` or `classic`)
+- auto-selects template by adapter when omitted (`ado_scrum` for ADO, `github_projects` for GitHub)
+- creates via adapter protocol (`github` or `ado`) and prints created `id`, `key`, and `url`
+
 ## Overview
 
 SpecFact CLI supports real-world agile/scrum practices through:

docs/reference/commands.md

@@ -3797,14 +3797,14 @@ specfact sync repository --repo . --watch --interval 2 --confidence 0.7
 
 ### `backlog` - Backlog Refinement and Template Management
 
-Backlog refinement commands for AI-assisted template-driven refinement of DevOps backlog items.
+Backlog refinement and dependency commands grouped under the `specfact backlog` command family.
 
 **Command Topology (recommended):**
 
 - `specfact backlog ceremony standup ...`
 - `specfact backlog ceremony refinement ...`
 - `specfact backlog delta status|impact|cost-estimate|rollback-analysis ...`
-- `specfact backlog analyze-deps|trace-impact|sync|verify-readiness|diff|promote|generate-release-notes ...`
+- `specfact backlog add|analyze-deps|trace-impact|sync|verify-readiness|diff|promote|generate-release-notes ...`
 
 Compatibility commands `specfact backlog daily` and `specfact backlog refine` remain available, but ceremony entrypoints are preferred for discoverability.
 
@@ -3855,6 +3855,33 @@ specfact backlog delta cost-estimate --project-id 1 --adapter github
 specfact backlog delta rollback-analysis --project-id 1 --adapter github
 ```
 
+#### `backlog add`
+
+Create a backlog item with optional parent hierarchy validation and DoR checks.
+
+```bash
+specfact backlog add --project-id <id> [OPTIONS]
+```
+
+**Common options:**
+
+- `--adapter ADAPTER` - Backlog adapter id (default: `github`)
+- `--template TEMPLATE` - Mapping template (default is adapter-aware: `github_projects` for GitHub, `ado_scrum` for ADO)
+- `--type TYPE` - Child type to create (for example `story`, `task`, `feature`)
+- `--parent REF` - Optional parent reference (id/key/title); validated against graph
+- `--title TEXT` - Issue title
+- `--body TEXT` - Issue description/body
+- `--acceptance-criteria TEXT` - Acceptance criteria content (also supported via interactive multiline input)
+- `--priority TEXT` - Optional priority value (for example `1`, `high`, `P1`)
+- `--story-points VALUE` - Optional story points (integer or float)
+- `--sprint TEXT` - Optional sprint/iteration path assignment
+- `--body-end-marker TEXT` - Sentinel marker for multiline input (default: `::END::`)
+- `--description-format TEXT` - Description rendering mode (`markdown` or `classic`)
+- `--non-interactive` - Fail fast on missing required inputs instead of prompting
+- `--check-dor` - Validate draft against `.specfact/dor.yaml` before create
+- `--repo-path PATH` - Repository path used to load DoR configuration (default `.`)
+- `--custom-config PATH` - Optional config containing `creation_hierarchy`
+
 #### `backlog analyze-deps`
 
 Build and analyze backlog dependency graph for a provider project.
@@ -3868,7 +3895,7 @@ specfact backlog analyze-deps --project-id <id> [OPTIONS]
 **Migration note:** `specfact module` is the canonical lifecycle command group. Init lifecycle flags remain supported as compatibility aliases.
 
 - `--adapter ADAPTER` - Backlog adapter id (default: `github`)
-- `--template TEMPLATE` - Mapping template (default: `github_projects`)
+- `--template TEMPLATE` - Mapping template (default is adapter-aware: `github_projects` for GitHub, `ado_scrum` for ADO)
 - `--custom-config PATH` - Optional custom mapping YAML
 - `--output PATH` - Optional markdown summary output
 - `--json-export PATH` - Optional graph JSON export
@@ -3886,7 +3913,7 @@ specfact backlog trace-impact <item-id> --project-id <id> [OPTIONS]
 **Migration note:** `specfact module` is the canonical lifecycle command group. Init lifecycle flags remain supported as compatibility aliases.
 
 - `--adapter ADAPTER` - Backlog adapter id (default: `github`)
-- `--template TEMPLATE` - Mapping template (default: `github_projects`)
+- `--template TEMPLATE` - Mapping template (default is adapter-aware: `github_projects` for GitHub, `ado_scrum` for ADO)
 - `--custom-config PATH` - Optional custom mapping YAML
 
 #### `backlog verify-readiness`
@@ -3902,7 +3929,7 @@ specfact backlog verify-readiness --project-id <id> [OPTIONS]
 **Migration note:** `specfact module` is the canonical lifecycle command group. Init lifecycle flags remain supported as compatibility aliases.
 
 - `--adapter ADAPTER` - Backlog adapter id (default: `github`)
-- `--template TEMPLATE` - Mapping template (default: `github_projects`)
+- `--template TEMPLATE` - Mapping template (default is adapter-aware: `github_projects` for GitHub, `ado_scrum` for ADO)
 - `--target-items CSV` - Optional comma-separated subset of item IDs
 
 #### `backlog diff`

modules/backlog-core/src/backlog_core/adapters/backlog_protocol.py

@@ -26,6 +26,13 @@ def fetch_all_issues(self, project_id: str, filters: dict[str, Any] | None = Non
     def fetch_relationships(self, project_id: str) -> list[dict[str, Any]]:
         """Fetch all issue/work-item relationships for a project."""
 
+    @beartype
+    @require(lambda project_id: project_id.strip() != "", "project_id must be non-empty")
+    @require(lambda payload: isinstance(payload, dict), "payload must be dict")
+    @ensure(lambda result: isinstance(result, dict), "create_issue must return dict")
+    def create_issue(self, project_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+        """Create a provider issue/work item and return id/key/url metadata."""
+
 
 @beartype
 @require(lambda adapter: adapter is not None, "adapter must be provided")
@@ -35,7 +42,7 @@ def require_backlog_graph_protocol(adapter: Any) -> BacklogGraphProtocol:
     if not isinstance(adapter, BacklogGraphProtocol):
         msg = (
             f"Adapter '{type(adapter).__name__}' does not support BacklogGraphProtocol. "
-            "Expected methods: fetch_all_issues(project_id, filters), fetch_relationships(project_id)."
+            "Expected methods: fetch_all_issues(project_id, filters), fetch_relationships(project_id), create_issue(project_id, payload)."
         )
         raise TypeError(msg)
     return adapter

modules/backlog-core/src/backlog_core/commands/__init__.py

@@ -3,6 +3,7 @@
 from specfact_cli.contracts.module_interface import ModuleIOContract
 from specfact_cli.modules import module_io_shim
 
+from .add import add
 from .analyze_deps import analyze_deps, trace_impact
 from .diff import diff
 from .promote import promote
@@ -20,6 +21,7 @@
 
 __all__ = [
     "BacklogGraphToPlanBundle",
+    "add",
     "analyze_deps",
     "commands_interface",
     "compute_delta",